semantica/docs/reference/ontology.md

title, description, icon

title	description	icon
Ontology Module	Automated ontology generation, SHACL validation, OWL/RDF export, namespace management, and LLM-powered ontology generation.	sitemap

semantica.ontology provides the full lifecycle for knowledge graph schemas — from auto-generation and SHACL validation to OWL/RDF export. Use it for schema design, data modeling, semantic web interoperability, and SHACL-based data quality validation.

Exported Classes

Class	Role
OntologyEngine	Unified facade orchestrating the full ontology lifecycle
OntologyGenerator	Auto-generate ontologies from KG data (6-stage pipeline)
LLMOntologyGenerator	LLM-powered ontology generation for complex domains
SHACLGenerator	Generate SHACL shapes from an ontology or KG schema
OntologyValidator	Validate any graph against SHACL shapes — returns SHACLValidationReport
OWLGenerator	Serialize ontologies to Turtle, RDF/XML, JSON-LD
NamespaceManager	IRI generation, prefix management, and namespace binding
OntologyEvaluator	Coverage, completeness, and granularity quality metrics
OntologyAligner	Align and merge ontologies across schemas
AssociativeClassBuilder	Model N-ary relationships as intermediate OWL classes

OntologyEngine (Unified Facade)

The OntologyEngine orchestrates the full ontology lifecycle — generation, validation, export, and versioning:

from semantica.ontology import OntologyEngine

engine = OntologyEngine(base_uri="https://example.org/ontology/")

# Generate ontology from KG data
ontology = engine.generate_ontology({"entities": entities, "relationships": relationships})

# Validate a graph against the generated SHACL shapes
report = engine.validate(kg)
if not report.conforms:
    for v in report.violations:
        print(f"{v.severity}: {v.message} on {v.node}")

# Export to OWL Turtle
engine.export(ontology, "ontology.ttl", format="turtle")

OntologyEngine Methods

Method	Description
generate_ontology(data)	Run the 6-stage pipeline on entity/relationship data
validate(kg)	Check a knowledge graph against generated SHACL shapes
export(ontology, path, format)	Serialize to "turtle", "xml", or "json-ld"
align(other_ontology)	Align and merge with another ontology
evaluate(ontology, kg)	Compute coverage, completeness, and granularity metrics

OntologyGenerator (6-Stage Pipeline)

Generate a formal ontology automatically from your knowledge graph entities and relationships:

from semantica.ontology import OntologyGenerator

generator = OntologyGenerator(base_uri="https://example.org/ontology/")
ontology  = generator.generate_ontology({
    "entities":      entities,
    "relationships": relationships,
})

The pipeline runs through these stages in order:

1. Semantic Network Parsing — extract concepts and patterns from entity/relationship data
2. YAML-to-Definition — transform patterns into intermediate class definitions
3. Definition-to-Types — map definitions to OWL types (owl:Class, owl:ObjectProperty)
4. Hierarchy Generation — build taxonomy trees using transitive closure and cycle detection
5. TTL Generation — serialize to Turtle format using rdflib
6. Quality Evaluation — assess coverage, completeness, and granularity metrics

SHACL Validation

Generate SHACL shapes from an ontology and validate any graph against them:

from semantica.ontology import SHACLGenerator, OntologyValidator, SHACLValidationReport, SHACLViolation

# Generate shapes from ontology
generator  = SHACLGenerator()
shapes     = generator.generate(ontology)
shapes_ttl = shapes.serialize(format="turtle")

# Validate a graph against the shapes
validator = OntologyValidator()
report: SHACLValidationReport = validator.validate(kg, shapes=shapes)

if not report.conforms:
    violation: SHACLViolation
    for violation in report.violations:
        print(f"{violation.severity}: {violation.message}")
        print(f"  Node: {violation.node}")
        print(f"  Path: {violation.path}")

Validation Report Fields

Field	Type	Description
conforms	bool	True if the graph passes all SHACL constraints
violations	List[SHACLViolation]	Detailed failure records
severity	str	"violation", "warning", or "info"
message	str	Human-readable constraint failure description
node	str	IRI of the violating graph node
path	str	IRI of the violating property path

LLM-Powered Ontology Generation

For complex or novel domains where schema patterns are hard to infer statistically:

from semantica.ontology import LLMOntologyGenerator
from semantica.llms import Groq
import os

llm = Groq(model="llama-3.3-70b-versatile", api_key=os.getenv("GROQ_API_KEY"))

generator = LLMOntologyGenerator(llm_provider=llm)
ontology  = generator.generate(
    domain_description="A biomedical ontology for clinical trial protocols",
    examples=["Patient", "Trial", "Intervention", "Outcome"],
)

OWL / RDF Export

from semantica.ontology import OWLGenerator

generator = OWLGenerator()
generator.generate(ontology, path="ontology.ttl",  format="turtle")
generator.generate(ontology, path="ontology.owl",  format="xml")
generator.generate(ontology, path="ontology.json", format="json-ld")

Namespace Management

from semantica.ontology import NamespaceManager

ns = NamespaceManager(base_uri="https://example.org/")
ns.register("ex",     "https://example.org/")
ns.register("schema", "https://schema.org/")
ns.register("owl",    "http://www.w3.org/2002/07/owl#")

# Generate IRIs for classes and properties
class_iri    = ns.generate_class_iri("Person")
property_iri = ns.generate_property_iri("worksFor")

Ontology Evaluation

Measure coverage, completeness, and granularity of a generated ontology:

from semantica.ontology import OntologyEvaluator

evaluator = OntologyEvaluator()
result    = evaluator.evaluate(ontology, kg)

print(f"Class coverage:    {result.class_coverage:.2f}")
print(f"Property coverage: {result.property_coverage:.2f}")
print(f"Completeness:      {result.completeness:.2f}")
print(f"Granularity:       {result.granularity:.2f}")

for gap in result.gaps:
    print(f"Gap: {gap.description}")

Ingest an Existing Ontology

Load and parse an ontology file for downstream use:

from semantica.ontology import ingest_ontology

ontology_data = ingest_ontology("schema.ttl")     # Turtle
ontology_data = ingest_ontology("schema.owl")     # OWL/XML
ontology_data = ingest_ontology("schema.jsonld")  # JSON-LD

Ontology Hub (v0.5.0)

A visual browser UI for the full ontology lifecycle. Launch via CLI:

pip install "semantica[explorer]"
semantica-explorer --port 8080
# Navigate to http://localhost:8080 → Ontology Hub tab

Features:

• Visual editor — create and edit classes, properties, and relationships in the browser
• SHACL Studio — author and validate SHACL shapes with live feedback
• Health dashboard — coverage, completeness, and constraint violation metrics
• Version control — snapshot, diff, and restore ontology versions

Ontology versioning (`VersionManager`, `OntologyVersion`) has moved to `semantica.change_management`. Import from there: `from semantica.change_management import VersionManager`. Apply inference rules over ontology axioms. The graph being modeled by the ontology. Export ontologies as RDF, OWL, or JSON-LD. Detect ontology constraint violations.