How to Manage Ontologies with Semantica: A Complete Guide to Generation, Versioning, and Visualization

Semantica provides a pluggable, six-stage pipeline for creating, version-controlling, and visualizing ontologies that govern knowledge graphs through three core components: OntologyGenerator, NamespaceManager, and OntologyVisualizer.

Managing ontologies with Semantica means transforming raw entity and relationship data into governed, versioned RDF/OWL structures with stable IRIs and interactive visualizations. The semantica-agi/semantica repository implements this through a modular Python stack that handles everything from semantic network parsing to Turtle export and stakeholder-ready diagrams.

Understanding the Core Components

Semantica's ontology management revolves around three specialized classes. Each handles a distinct phase of the ontology lifecycle:

Component	Source File	Primary Responsibility
OntologyGenerator	semantica/ontology/ontology_generator.py	Builds ontologies from raw data via a 6-stage pipeline
NamespaceManager	semantica/ontology/namespace_manager.py	Centralizes IRI creation, versioning, and naming conventions
OntologyVisualizer	semantica/visualization/ontology_visualizer.py	Renders class hierarchies, property graphs, and metrics

These components work sequentially: raw data flows into the generator, which relies on the namespace manager for stable identifiers, and the visualizer provides inspection and communication tools for the result.

Generating Ontologies with OntologyGenerator

The OntologyGenerator class implements a deterministic pipeline that converts unstructured entity-relationship data into structured OWL-compatible ontologies.

The Six-Stage Pipeline

Lines 58-65 of ontology_generator.py define the following stages:

1. Semantic Network Parsing — Extracts concepts from input entities and relationships dictionaries
2. YAML-to-Definition — Converts parsed networks into class-definition dictionaries
3. Definition-to-Types — Maps definitions to OWL types (class, property, individual)
4. Hierarchy Generation — Builds taxonomic trees from subclass relationships
5. TTL Generation — Emits RDF/Turtle using rdflib through an internal OWL generator
6. Symbolic Validation — Runs HermiT/Pellet reasoning to verify logical consistency

The generator returns a structured dictionary containing uri, name, version, classes, and properties (lines 44-49).

Basic Ontology Generation Example

from semantica.ontology import OntologyGenerator

generator = OntologyGenerator(
    base_uri="https://example.org/ontology/",
    min_occurrences=2
)

raw_data = {
    "entities": [
        {"type": "Person", "name": "Alice"},
        {"type": "Company", "name": "Acme Corp"}
    ],
    "relationships": [
        {"type": "employs", "source": "Acme Corp", "target": "Alice"}
    ]
}

ontology = generator.generate_ontology(raw_data, name="AcmeOntology")
print(ontology["uri"])               # → https://example.org/ontology/

print(len(ontology["classes"]))      # → number of inferred classes

print(len(ontology["properties"]))   # → number of inferred properties

The min_occurrences parameter filters low-frequency entities, ensuring only statistically significant concepts enter the ontology.

Managing Namespaces and IRIs with NamespaceManager

Stable, versioned IRIs are critical for ontology governance. The NamespaceManager class centralizes this responsibility in semantica/ontology/namespace_manager.py.

IRI Generation Methods

• get_base_uri() (lines 98-100) — Automatically appends version suffixes (v{version}/) when version ≠ "1.0"
• generate_class_iri() (lines 13-26) — Creates PascalCase "speaking IRIs" or deterministic hash-based alternatives
• generate_property_iri() (lines 39-50) — Produces camelCase property identifiers
• generate_individual_iri() (lines 65-75) — Normalizes names and places them under the individual/ segment

Pre-registered Vocabularies

Lines 80-88 automatically register standard namespaces:

RDF, RDFS, OWL, XSD, SKOS, DC  # Dublin Core

Custom Namespace Configuration

from semantica.ontology import NamespaceManager, OntologyGenerator

ns_mgr = NamespaceManager(
    base_uri="https://myorg.com/ont/",
    version="2.1",
    use_speaking_iris=True  # Human-readable PascalCase/camelCase

)

ns_mgr.register_namespace("ex", "https://myorg.com/vocab/")

generator = OntologyGenerator(namespace_manager=ns_mgr)

Passing a custom NamespaceManager to OntologyGenerator ensures all generated IRIs follow your organizational conventions and versioning scheme.

Visualizing Ontologies with OntologyVisualizer

The OntologyVisualizer in semantica/visualization/ontology_visualizer.py transforms ontologies into inspectable diagrams for debugging and stakeholder communication.

Available Visualization Methods

Method	Purpose	Output Formats
visualize_hierarchy()	Class taxonomic tree	Plotly (interactive), Graphviz DOT
visualize_properties()	Domain/range property graph	Plotly, DOT
visualize_structure()	Full ontology network	Plotly, DOT
visualize_class_property_matrix()	Class-property association heatmap	Plotly
visualize_metrics()	Statistical summary	Plotly

Dependency Handling

Lines 103-116 implement strict dependency checking. Missing graphviz or plotly packages raise ProcessingError with explicit installation hints:

# Raises ProcessingError if plotly not installed

viz.visualize_hierarchy(ontology, output="interactive")

# Raises ProcessingError if graphviz not installed

viz.visualize_hierarchy(ontology, output="dot")

Interactive Hierarchy Visualization

from semantica.visualization import OntologyVisualizer

viz = OntologyVisualizer(color_scheme="default", node_size=20)

fig = viz.visualize_hierarchy(
    ontology,
    output="interactive",
    node_color_by="level",        # Color by hierarchy depth

    node_size_by="instances",     # Size by instance count

    hover_data=["name", "description"]
)

fig.show()  # In Jupyter or compatible environments

Static Graphviz Export

viz.visualize_hierarchy(
    ontology,
    output="dot",
    file_path="ontology_hierarchy.dot"
)

# Render: dot -Tpng ontology_hierarchy.dot -o hierarchy.png

All visualization methods integrate with Semantica's CLI through self.progress_tracker.start_tracking (lines 57-61), enabling progress bars during long-running renders.

Complete Integration Workflow

A typical ontology management workflow with Semantica follows five steps:

1. Initialize namespace management — Create or accept default NamespaceManager
2. Configure the generator — Instantiate OntologyGenerator with base URI and namespace manager
3. Execute generation — Call generate_ontology() with raw entity-relationship data
4. Persist results — Export to Turtle via semantica.io.owl_exporter or similar
5. Visualize and validate — Use OntologyVisualizer for inspection and reporting

Summary

• OntologyGenerator provides a deterministic 6-stage pipeline from raw data to validated OWL structures, implemented in semantica/ontology/ontology_generator.py
• NamespaceManager ensures versioned, convention-compliant IRIs through methods like generate_class_iri() and get_base_uri() in semantica/ontology/namespace_manager.py
• OntologyVisualizer delivers five visualization modes with automatic dependency checking in semantica/visualization/ontology_visualizer.py
• All components are pure Python with optional dependencies (graphviz, plotly) and comprehensive test coverage in tests/visualization/

Frequently Asked Questions

How does Semantica handle ontology versioning?

The NamespaceManager automatically appends version suffixes to base URIs when version ≠ "1.0" (lines 98-100 of namespace_manager.py). Pass version="2.1" during initialization and all generated IRIs inherit this versioning scheme.

Can I use Semantica without installing Graphviz or Plotly?

Yes. Both are optional dependencies. The core ontology generation and namespace management functions rely only on standard libraries. Visualization methods raise ProcessingError with installation instructions if optional dependencies are missing (lines 103-116 of ontology_visualizer.py).

What output formats does OntologyGenerator produce?

The generator returns a Python dictionary with uri, name, version, classes, and properties keys (lines 44-49 of ontology_generator.py). Turtle/OWL serialization occurs through stage 5 (TTL Generation) using internal rdflib integration; use semantica.io.owl_exporter for file persistence.

How are class and property names formatted?

When use_speaking_iris=True, the NamespaceManager enforces PascalCase for classes (lines 13-26) and camelCase for properties (lines 39-50). Disable this for deterministic hash-based IRIs suitable for stable, opaque identifiers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}