Ontology Engineering

Ontology Engineering Workflow

You have access to the Open Ontologies MCP server, which provides 50+ tools for AI-native ontology engineering backed by an in-memory Oxigraph triple store.

Core Workflow

When building or modifying ontologies, follow this workflow. Decide which tools to call and in what order based on results -- this is not a fixed pipeline.

1. Generate

• Understand the domain requirements (natural language, competency questions, methodology constraints)
• Generate Turtle/OWL directly -- you know OWL, RDF, BORO, 4D modeling natively

2. Validate and Load

• Call onto_validate on the generated Turtle -- if it fails, fix syntax errors and re-validate
• Call onto_load to load into the Oxigraph triple store. For repos that mount a folder of .ttl files via [general] ontology_dirs, prefer onto_repo_load so the same compile-cache / TTL-eviction path is exercised. Use onto_repo_list to discover candidate files.
• Call onto_stats to verify class count, property count, triple count match expectations

3. Verify

• Call onto_lint to check for missing labels, comments, domains, ranges -- fix any issues found
• Call onto_query with SPARQL to verify structure (expected classes, subclass hierarchies, competency questions)
• If a reference ontology exists, call onto_diff to compare

4. Iterate

• If any step reveals problems, fix the Turtle and restart from step 2
• Continue until validation passes, stats match, lint is clean, and SPARQL queries return expected results

5. Persist

• Call onto_save to write the final ontology to a .ttl file
• Call onto_version to save a named snapshot for rollback

Cache and Multi-Ontology Loading

The server keeps a single active ontology in memory plus an on-disk N-Triples compile cache for everything it has parsed. Switch between several ontologies without paying re-parse costs:

• onto_repo_list — enumerate .ttl / .owl / .nt / .rdf / .nq / .trig / .jsonld files configured under [general] ontology_dirs. Container-friendly: mount a host folder of TTL files and discover them at runtime without hardcoded paths.
• onto_repo_load — load by bare file stem, relative path, or absolute path inside a configured repo dir. Reuses the same compile-cache / TTL-eviction path as onto_load.
• onto_cache_status / onto_cache_list — inspect what is cached, what is currently active, and the effective [cache] configuration (TTL, auto_refresh, dir).
• onto_cache_remove — drop a cached entry by name (pass delete_file=false to keep the on-disk N-Triples for a later reload).
• onto_unload — drop the active ontology (or a specific cached entry by name) from memory; the on-disk cache is preserved unless delete_cache=true.
• onto_recompile — force a re-parse from source, ignoring the cache. Without name, recompiles the active ontology and reloads it; with name, rebuilds a non-active entry without disturbing the active in-memory store.

Ontology Lifecycle (Terraform-style)

For evolving ontologies in production:

1. Plan — onto_plan shows added/removed classes, blast radius, risk score. Check onto_lock for protected IRIs.
2. Enforce — onto_enforce with a rule pack (generic, boro, value_partition, hierarchy) checks design pattern compliance.
3. Apply — onto_apply with mode safe (clear + reload) or migrate (add equivalentClass bridges).
4. Monitor — onto_monitor runs SPARQL watchers with threshold alerts. Use onto_monitor_clear if blocked.
5. Drift — onto_drift compares versions with rename detection and self-calibrating confidence.
6. Lineage — onto_lineage shows the full plan → enforce → apply → monitor → drift trail for the current session.

Data Extension Workflow

When applying an ontology to external data:

1. onto_map — generate mapping config from data schema + loaded ontology
2. onto_ingest — parse a structured file (CSV, JSON, NDJSON, XML, YAML, XLSX, Parquet) into RDF
3. onto_sql_ingest — run a SQL query against PostgreSQL or DuckDB (via postgres://, duckdb:///path.duckdb, :memory:, or a *.duckdb file path) and ingest result rows. Use this when the source data lives in a database, or when you want to use DuckDB as a federation layer over remote Parquet/CSV/JSON via the httpfs, postgres_scanner, iceberg, etc. extensions.
4. onto_import_schema — introspect a PostgreSQL or DuckDB schema and generate OWL classes/properties/cardinality from tables/columns/PKs/FKs.
5. onto_shacl — validate against SHACL shapes
6. onto_reason — run RDFS or OWL-RL inference
7. Or use onto_extend to run the full file-based pipeline (ingest + SHACL + reason) in one call

Reasoning and DL Explanation

• onto_reason — RDFS / OWL-RL forward-chaining materialisation
• onto_dl_check — check subClass ⊑ superClass using DL tableaux
• onto_dl_explain — return the clash trace explaining why a class is unsatisfiable

Semantic Search and Embeddings

After loading, generate embeddings to enable natural-language search:

• onto_embed — generate text + Poincaré structural embeddings for every class. Honours [embeddings] provider = "local" | "openai" and the OPEN_ONTOLOGIES_EMBEDDINGS_* env vars.
• onto_search — natural-language query → most-similar classes (mode: "text" | "structure" | "product").
• onto_similarity — compute cosine + Poincaré distance between two specific IRIs.

When embeddings exist, onto_align automatically uses them as a 7th alignment signal, catching semantically equivalent classes whose labels differ.

Tool Reference

Key Principle

Dynamically decide the next tool call based on what the previous tool returned. If onto_validate fails, fix and retry. If onto_stats shows wrong counts, regenerate. If onto_lint finds missing labels, add them. The MCP tools are individual operations -- you are the orchestrator.