mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-04-25 08:26:21 +02:00

Alex Jenkins 8954fa3ad7 Feat: TrustGraph i18n & Documentation Translation Updates (#781 )

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.

2026-04-14 12:08:32 +01:00

9.8 KiB

Raw Blame History

layout	title	parent
default	Ontology Structure Technical Specification	Tech Specs

Ontology Structure Technical Specification

Overview

This specification describes the structure and format of ontologies within the TrustGraph system. Ontologies provide formal knowledge models that define classes, properties, and relationships, supporting reasoning and inference capabilities. The system uses an OWL-inspired configuration format that broadly represents OWL/RDFS concepts while being optimized for TrustGraph's requirements.

Naming Convention: This project uses kebab-case for all identifiers (configuration keys, API endpoints, module names, etc.) rather than snake_case.

Goals

Class and Property Management: Define OWL-like classes with properties, domains, ranges, and type constraints
Rich Semantic Support: Enable comprehensive RDFS/OWL properties including labels, multi-language support, and formal constraints
Multi-Ontology Support: Allow multiple ontologies to coexist and interoperate
Validation and Reasoning: Ensure ontologies conform to OWL-like standards with consistency checking and inference support
Standard Compatibility: Support import/export in standard formats (Turtle, RDF/XML, OWL/XML) while maintaining internal optimization

Background

TrustGraph stores ontologies as configuration items in a flexible key-value system. While the format is inspired by OWL (Web Ontology Language), it is optimized for TrustGraph's specific use cases and does not strictly adhere to all OWL specifications.

Ontologies in TrustGraph enable:

Definition of formal object types and their properties
Specification of property domains, ranges, and type constraints
Logical reasoning and inference
Complex relationships and cardinality constraints
Multi-language support for internationalization

Ontology Structure

Configuration Storage

Ontologies are stored as configuration items with the following pattern:

Type: ontology
Key: Unique ontology identifier (e.g., natural-world, domain-model)
Value: Complete ontology in JSON format

JSON Structure

The ontology JSON format consists of four main sections:

1. Metadata

Contains administrative and descriptive information about the ontology:

{
  "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#"]
  }
}

Fields:

name: Human-readable name of the ontology
description: Brief description of the ontology's purpose
version: Semantic version number
created: ISO 8601 timestamp of creation
modified: ISO 8601 timestamp of last modification
creator: Identifier of the creating user/system
namespace: Base URI for ontology elements
imports: Array of imported ontology URIs

2. Classes

Defines the object types and their hierarchical relationships:

{
  "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"
    }
  }
}

Supported Properties:

uri: Full URI of the class
type: Always "owl:Class"
rdfs:label: Array of language-tagged labels
rdfs:comment: Description of the class
rdfs:subClassOf: Parent class identifier (single inheritance)
owl:equivalentClass: Array of equivalent class identifiers
owl:disjointWith: Array of disjoint class identifiers
dcterms:identifier: Optional external reference identifier

3. Object Properties

Properties that link instances to other instances:

{
  "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
    }
  }
}

Supported Properties:

uri: Full URI of the property
type: Always "owl:ObjectProperty"
rdfs:label: Array of language-tagged labels
rdfs:comment: Description of the property
rdfs:domain: Class identifier that has this property
rdfs:range: Class identifier for property values
owl:inverseOf: Identifier of inverse property
owl:functionalProperty: Boolean indicating at most one value
owl:inverseFunctionalProperty: Boolean for unique identifying properties

4. Datatype Properties

Properties that link instances to literal values:

{
  "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
    }
  }
}

Supported Properties:

uri: Full URI of the property
type: Always "owl:DatatypeProperty"
rdfs:label: Array of language-tagged labels
rdfs:comment: Description of the property
rdfs:domain: Class identifier that has this property
rdfs:range: XSD datatype for property values
owl:functionalProperty: Boolean indicating at most one value
owl:minCardinality: Minimum number of values (optional)
owl:maxCardinality: Maximum number of values (optional)
owl:cardinality: Exact number of values (optional)

Supported XSD Datatypes

The following XML Schema datatypes are supported for datatype property ranges:

xsd:string - Text values
xsd:integer - Integer numbers
xsd:nonNegativeInteger - Non-negative integers
xsd:float - Floating point numbers
xsd:double - Double precision numbers
xsd:boolean - True/false values
xsd:dateTime - Date and time values
xsd:date - Date values
xsd:anyURI - URI references

Language Support

Labels and comments support multiple languages using the W3C language tag format:

{
  "rdfs:label": [
    {"value": "Animal", "lang": "en"},
    {"value": "Tier", "lang": "de"},
    {"value": "Animal", "lang": "es"}
  ]
}

Example Ontology

Here's a complete example of a simple ontology:

{
  "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"
    }
  }
}

Validation Rules

Structural Validation

URI Consistency: All URIs should follow the pattern {namespace}#{identifier}
Class Hierarchy: No circular inheritance in rdfs:subClassOf
Property Domains/Ranges: Must reference existing classes or valid XSD types
Disjoint Classes: Cannot be subclasses of each other
Inverse Properties: Must be bidirectional if specified

Semantic Validation

Unique Identifiers: Class and property identifiers must be unique within an ontology
Language Tags: Must follow BCP 47 language tag format
Cardinality Constraints: minCardinality ≤ maxCardinality when both specified
Functional Properties: Cannot have maxCardinality > 1

Import/Export Format Support

While the internal format is JSON, the system supports conversion to/from standard ontology formats:

Turtle (.ttl) - Compact RDF serialization
RDF/XML (.rdf, .owl) - W3C standard format
OWL/XML (.owx) - OWL-specific XML format
JSON-LD (.jsonld) - JSON for Linked Data

9.8 KiB Raw Blame History

Ontology Structure Technical Specification

Overview

Goals

Background

Ontology Structure

Configuration Storage

JSON Structure

1. Metadata

2. Classes

3. Object Properties

4. Datatype Properties

Supported XSD Datatypes

Language Support

Example Ontology

Validation Rules

Structural Validation

Semantic Validation

Import/Export Format Support

References

9.8 KiB

Raw Blame History