/ontology-engineering

name: ontology-engineering
description: Build, validate, and govern RDF/OWL ontologies using the Open Ontologies MCP server. Use when the user asks to create, modify, query, or manage ontologies, knowledge graphs, or RDF data.

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

| Tool | When to use | | ---- | ----------- | | `onto_status` | Check that the server is running and how many triples are loaded |