mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
8954fa3ad7
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
294 lines
11 KiB
Markdown
294 lines
11 KiB
Markdown
---
|
|
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)
|