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

> Learn to manage ontologies with Semantica. This guide covers generation, versioning, and visualization using its powerful pipeline and core components.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_generator.py) | Builds ontologies from raw data via a 6-stage pipeline |
| **NamespaceManager** | [`semantica/ontology/namespace_manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/namespace_manager.py) | Centralizes IRI creation, versioning, and naming conventions |
| **OntologyVisualizer** | [`semantica/visualization/ontology_visualizer.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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:

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

```

### Custom Namespace Configuration

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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:

```python

# 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

```python
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

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/namespace_manager.py)
- **OntologyVisualizer** delivers five visualization modes with automatic dependency checking in [`semantica/visualization/ontology_visualizer.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.