mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 17:06:22 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
294
docs/tech-specs/pt/ontology.pt.md
Normal file
294
docs/tech-specs/pt/ontology.pt.md
Normal file
|
|
@ -0,0 +1,294 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Especificação Técnica da Estrutura da Ontologia"
|
||||
parent: "Portuguese (Beta)"
|
||||
---
|
||||
|
||||
# Especificação Técnica da Estrutura da Ontologia
|
||||
|
||||
> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Esta especificação descreve a estrutura e o formato das ontologias dentro do sistema TrustGraph. As ontologias fornecem modelos de conhecimento formais que definem classes, propriedades e relacionamentos, suportando capacidades de raciocínio e inferência. O sistema usa um formato de configuração inspirado em OWL que representa amplamente os conceitos OWL/RDFS, ao mesmo tempo que é otimizado para os requisitos do TrustGraph.
|
||||
|
||||
**Convenção de Nomenclatura**: Este projeto usa kebab-case para todos os identificadores (chaves de configuração, pontos finais de API, nomes de módulos, etc.) em vez de snake_case.
|
||||
|
||||
## Objetivos
|
||||
|
||||
**Gerenciamento de Classes e Propriedades**: Definir classes semelhantes a OWL com propriedades, domínios, intervalos e restrições de tipo.
|
||||
**Suporte Semântico Rico**: Habilitar propriedades abrangentes RDFS/OWL, incluindo rótulos, suporte multilíngue e restrições formais.
|
||||
**Suporte a Múltiplas Ontologias**: Permitir que várias ontologias coexistam e interoperem.
|
||||
**Validação e Raciocínio**: Garantir que as ontologias estejam em conformidade com padrões semelhantes a OWL, com verificação de consistência e suporte de inferência.
|
||||
**Compatibilidade com Padrões**: Suportar importação/exportação em formatos padrão (Turtle, RDF/XML, OWL/XML) mantendo a otimização interna.
|
||||
|
||||
## Contexto
|
||||
|
||||
O TrustGraph armazena ontologias como itens de configuração em um sistema flexível de chave-valor. Embora o formato seja inspirado em OWL (Web Ontology Language), ele é otimizado para casos de uso específicos do TrustGraph e não adere estritamente a todas as especificações do OWL.
|
||||
|
||||
As ontologias no TrustGraph permitem:
|
||||
Definição de tipos de objetos formais e suas propriedades.
|
||||
Especificação de domínios, intervalos e restrições de tipo de propriedade.
|
||||
Raciocínio e inferência lógica.
|
||||
Relacionamentos complexos e restrições de cardinalidade.
|
||||
Suporte multilíngue para internacionalização.
|
||||
|
||||
## Estrutura da Ontologia
|
||||
|
||||
### Armazenamento de Configuração
|
||||
|
||||
As ontologias são armazenadas como itens de configuração com o seguinte padrão:
|
||||
**Tipo**: `ontology`
|
||||
**Chave**: Identificador de ontologia exclusivo (por exemplo, `natural-world`, `domain-model`)
|
||||
**Valor**: Ontologia completa em formato JSON.
|
||||
|
||||
### Estrutura JSON
|
||||
|
||||
O formato JSON da ontologia consiste em quatro seções principais:
|
||||
|
||||
#### 1. Metadados
|
||||
|
||||
Contém informações administrativas e descritivas sobre a ontologia:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "The natural world",
|
||||
"description": "Ontology covering the natural order",
|
||||
"version": "1.0.0",
|
||||
"created": "2025-09-20T12:07:37.068Z",
|
||||
"modified": "2025-09-20T12:12:20.725Z",
|
||||
"creator": "current-user",
|
||||
"namespace": "http://trustgraph.ai/ontologies/natural-world",
|
||||
"imports": ["http://www.w3.org/2002/07/owl#"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Campos:**
|
||||
`name`: Nome legível para humanos da ontologia
|
||||
`description`: Breve descrição do propósito da ontologia
|
||||
`version`: Número de versão semântico
|
||||
`created`: Carimbo de data/hora ISO 8601 de criação
|
||||
`modified`: Carimbo de data/hora ISO 8601 da última modificação
|
||||
`creator`: Identificador do usuário/sistema que criou
|
||||
`namespace`: URI base para elementos da ontologia
|
||||
`imports`: Array de URIs de ontologias importadas
|
||||
|
||||
#### 2. Classes
|
||||
|
||||
Define os tipos de objeto e seus relacionamentos hierárquicos:
|
||||
|
||||
```json
|
||||
{
|
||||
"classes": {
|
||||
"animal": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#animal",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Animal", "lang": "en"}],
|
||||
"rdfs:comment": "An animal",
|
||||
"rdfs:subClassOf": "lifeform",
|
||||
"owl:equivalentClass": ["creature"],
|
||||
"owl:disjointWith": ["plant"],
|
||||
"dcterms:identifier": "ANI-001"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Propriedades Suportadas:**
|
||||
`uri`: URI completo da classe
|
||||
`type`: Sempre `"owl:Class"`
|
||||
`rdfs:label`: Array de rótulos com informações de idioma
|
||||
`rdfs:comment`: Descrição da classe
|
||||
`rdfs:subClassOf`: Identificador da classe pai (herança simples)
|
||||
`owl:equivalentClass`: Array de identificadores de classes equivalentes
|
||||
`owl:disjointWith`: Array de identificadores de classes disjuntas
|
||||
`dcterms:identifier`: Identificador de referência externa opcional
|
||||
|
||||
#### 3. Propriedades de Objeto
|
||||
|
||||
Propriedades que conectam instâncias a outras instâncias:
|
||||
|
||||
```json
|
||||
{
|
||||
"objectProperties": {
|
||||
"has-parent": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#has-parent",
|
||||
"type": "owl:ObjectProperty",
|
||||
"rdfs:label": [{"value": "has parent", "lang": "en"}],
|
||||
"rdfs:comment": "Links an animal to its parent",
|
||||
"rdfs:domain": "animal",
|
||||
"rdfs:range": "animal",
|
||||
"owl:inverseOf": "parent-of",
|
||||
"owl:functionalProperty": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Propriedades Suportadas:**
|
||||
`uri`: URI completo da propriedade
|
||||
`type`: Sempre `"owl:ObjectProperty"`
|
||||
`rdfs:label`: Array de rótulos com informações de idioma
|
||||
`rdfs:comment`: Descrição da propriedade
|
||||
`rdfs:domain`: Identificador da classe que possui esta propriedade
|
||||
`rdfs:range`: Identificador da classe para valores de propriedade
|
||||
`owl:inverseOf`: Identificador da propriedade inversa
|
||||
`owl:functionalProperty`: Booleano indicando no máximo um valor
|
||||
`owl:inverseFunctionalProperty`: Booleano para propriedades de identificação única
|
||||
|
||||
#### 4. Propriedades de Tipo de Dado
|
||||
|
||||
Propriedades que conectam instâncias a valores literais:
|
||||
|
||||
```json
|
||||
{
|
||||
"datatypeProperties": {
|
||||
"number-of-legs": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#number-of-legs",
|
||||
"type": "owl:DatatypeProperty",
|
||||
"rdfs:label": [{"value": "number of legs", "lang": "en"}],
|
||||
"rdfs:comment": "Count of number of legs of the animal",
|
||||
"rdfs:domain": "animal",
|
||||
"rdfs:range": "xsd:nonNegativeInteger",
|
||||
"owl:functionalProperty": true,
|
||||
"owl:minCardinality": 0,
|
||||
"owl:maxCardinality": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Propriedades Suportadas:**
|
||||
`uri`: URI completo da propriedade
|
||||
`type`: Sempre `"owl:DatatypeProperty"`
|
||||
`rdfs:label`: Array de rótulos com marcação de idioma
|
||||
`rdfs:comment`: Descrição da propriedade
|
||||
`rdfs:domain`: Identificador da classe que possui esta propriedade
|
||||
`rdfs:range`: Tipo de dados XSD para os valores da propriedade
|
||||
`owl:functionalProperty`: Booleano indicando no máximo um valor
|
||||
`owl:minCardinality`: Número mínimo de valores (opcional)
|
||||
`owl:maxCardinality`: Número máximo de valores (opcional)
|
||||
`owl:cardinality`: Número exato de valores (opcional)
|
||||
|
||||
### Tipos de Dados XSD Suportados
|
||||
|
||||
Os seguintes tipos de dados XML Schema são suportados para intervalos de propriedades:
|
||||
|
||||
`xsd:string` - Valores de texto
|
||||
`xsd:integer` - Números inteiros
|
||||
`xsd:nonNegativeInteger` - Inteiros não negativos
|
||||
`xsd:float` - Números de ponto flutuante
|
||||
`xsd:double` - Números de precisão dupla
|
||||
`xsd:boolean` - Valores verdadeiro/falso
|
||||
`xsd:dateTime` - Valores de data e hora
|
||||
`xsd:date` - Valores de data
|
||||
`xsd:anyURI` - Referências de URI
|
||||
|
||||
### Suporte a Idiomas
|
||||
|
||||
Rótulos e comentários suportam vários idiomas usando o formato de etiqueta de idioma W3C:
|
||||
|
||||
```json
|
||||
{
|
||||
"rdfs:label": [
|
||||
{"value": "Animal", "lang": "en"},
|
||||
{"value": "Tier", "lang": "de"},
|
||||
{"value": "Animal", "lang": "es"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Exemplo de Ontologia
|
||||
|
||||
Aqui está um exemplo completo de uma ontologia simples:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "The natural world",
|
||||
"description": "Ontology covering the natural order",
|
||||
"version": "1.0.0",
|
||||
"created": "2025-09-20T12:07:37.068Z",
|
||||
"modified": "2025-09-20T12:12:20.725Z",
|
||||
"creator": "current-user",
|
||||
"namespace": "http://trustgraph.ai/ontologies/natural-world",
|
||||
"imports": ["http://www.w3.org/2002/07/owl#"]
|
||||
},
|
||||
"classes": {
|
||||
"lifeform": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#lifeform",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Lifeform", "lang": "en"}],
|
||||
"rdfs:comment": "A living thing"
|
||||
},
|
||||
"animal": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#animal",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Animal", "lang": "en"}],
|
||||
"rdfs:comment": "An animal",
|
||||
"rdfs:subClassOf": "lifeform"
|
||||
},
|
||||
"cat": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#cat",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Cat", "lang": "en"}],
|
||||
"rdfs:comment": "A cat",
|
||||
"rdfs:subClassOf": "animal"
|
||||
},
|
||||
"dog": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#dog",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Dog", "lang": "en"}],
|
||||
"rdfs:comment": "A dog",
|
||||
"rdfs:subClassOf": "animal",
|
||||
"owl:disjointWith": ["cat"]
|
||||
}
|
||||
},
|
||||
"objectProperties": {},
|
||||
"datatypeProperties": {
|
||||
"number-of-legs": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#number-of-legs",
|
||||
"type": "owl:DatatypeProperty",
|
||||
"rdfs:label": [{"value": "number-of-legs", "lang": "en"}],
|
||||
"rdfs:comment": "Count of number of legs of the animal",
|
||||
"rdfs:range": "xsd:nonNegativeInteger",
|
||||
"rdfs:domain": "animal"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Regras de Validação
|
||||
|
||||
### Validação Estrutural
|
||||
|
||||
1. **Consistência de URIs**: Todos os URIs devem seguir o padrão `{namespace}#{identifier}`
|
||||
2. **Hierarquia de Classes**: Não pode haver herança circular em `rdfs:subClassOf`
|
||||
3. **Domínios/Intervalos de Propriedades**: Deve referenciar classes existentes ou tipos XSD válidos
|
||||
4. **Classes Disjuntas**: Não podem ser subclasses umas das outras
|
||||
5. **Propriedades Inversas**: Devem ser bidirecionais se especificadas
|
||||
|
||||
### Validação Semântica
|
||||
|
||||
1. **Identificadores Únicos**: Os identificadores de classe e propriedade devem ser únicos dentro de uma ontologia
|
||||
2. **Etiquetas de Idioma**: Devem seguir o formato de etiqueta de idioma BCP 47
|
||||
3. **Restrições de Cardinalidade**: `minCardinality` ≤ `maxCardinality` quando ambos são especificados
|
||||
4. **Propriedades Funcionais**: Não podem ter `maxCardinality` > 1
|
||||
|
||||
## Suporte a Formatos de Importação/Exportação
|
||||
|
||||
Embora o formato interno seja JSON, o sistema suporta a conversão para/de formatos de ontologia padrão:
|
||||
|
||||
**Turtle (.ttl)** - Serialização RDF compacta
|
||||
**RDF/XML (.rdf, .owl)** - Formato padrão W3C
|
||||
**OWL/XML (.owx)** - Formato XML específico para OWL
|
||||
**JSON-LD (.jsonld)** - JSON para Dados Vinculados
|
||||
|
||||
## Referências
|
||||
|
||||
[OWL 2 Web Ontology Language](https://www.w3.org/TR/owl2-overview/)
|
||||
[RDF Schema 1.1](https://www.w3.org/TR/rdf-schema/)
|
||||
[XML Schema Datatypes](https://www.w3.org/TR/xmlschema-2/)
|
||||
[BCP 47 Language Tags](https://tools.ietf.org/html/bcp47)
|
||||
Loading…
Add table
Add a link
Reference in a new issue