| name | ontology-engineer |
| description | Use when building, modifying, or validating ontologies. Orchestrates the onto_* MCP tools in a generate-validate-iterate loop. Triggers on "ontology", "OWL", "RDF", "Turtle", "SPARQL", "BORO", "4D modeling", or /ontology-engineer. |
Ontology Engineer
AI-native ontology engineering using OpenCheir's onto_* MCP tools (50+ tools).
When to Use
- User asks to build, extend, or modify an ontology
- User asks to validate, lint, or query an existing ontology
- User mentions OWL, RDF, Turtle, SPARQL, BORO, 4D modeling, IES4
- User wants to compare ontologies or run competency questions
- User needs to ingest tabular data, SQL query results, or a database schema into RDF
- User wants to run reasoning (RDFS / OWL-RL) or DL satisfiability checks
Prerequisites
The onto_* tools must be available via the OpenCheir MCP server. If they're not available, tell the user to install OpenCheir.
Workflow
Claude dynamically decides which tool to call next based on results. This is NOT a fixed pipeline — adapt based on what each tool returns.
Phase 1: Understand
- What domain? (Pizza, buildings, healthcare, etc.)
- What methodology? (standard OWL, BORO/4D, SKOS, etc.)
- What are the competency questions? (what should the ontology be able to answer?)
- Is there a reference ontology to compare against?
- Is the source data a file, a SQL database (Postgres / DuckDB), or a federated SQL query?
Phase 2: Generate or Import
- For greenfield: generate Turtle/OWL directly from domain knowledge.
- For an existing relational schema: call
onto_import_schema with a Postgres or DuckDB connection string — it generates OWL classes, datatype/object properties, and cardinality from tables/columns/PKs/FKs.
- For an existing on-disk corpus: configure
[general] ontology_dirs and use onto_repo_list / onto_repo_load to discover and load.
Phase 3: Validate (loop until clean)
onto_validate → syntax errors? → fix Turtle, re-validate
onto_load → loaded ok? → proceed to verification
onto_stats → counts match? → if not, regenerate missing parts
onto_lint → issues found? → fix labels/domains/ranges, re-load
Phase 4: Verify (loop until correct)
onto_query → run SPARQL to check structure / competency questions
onto_diff → compare vs a reference if one exists
onto_dl_check → spot-check tricky subClass relations via DL tableaux
onto_dl_explain → if a class is unsatisfiable, get the clash trace
Phase 5: Apply Data (optional)
onto_map → auto-generate a mapping from sample data + ontology
onto_ingest → file-based: CSV/JSON/NDJSON/XML/YAML/XLSX/Parquet → RDF
onto_sql_ingest → SQL-based: SELECT against Postgres or DuckDB → RDF
onto_shacl → validate ingested data against shapes
onto_reason → materialise inferred triples (rdfs / owl-rl)
onto_extend → file-based shortcut: ingest + SHACL + reason in one call
Phase 6: Persist + Govern
onto_version → save snapshot before finalizing
onto_save → write to .ttl file
onto_plan / onto_enforce / onto_apply / onto_monitor / onto_drift
→ Terraform-style lifecycle for evolving ontologies
Key Rules
- Always validate before loading —
onto_validate catches syntax errors that would silently fail
- Always check stats after loading —
onto_stats catches missing classes/properties
- Always lint after loading —
onto_lint catches missing labels and domains
- Version before pushing —
onto_version before onto_push (enforcer rule)
- Iterate, don't declare done — if any check fails, fix and re-run from Phase 3
- Use embeddings for semantic search and alignment — call
onto_embed once after onto_load, then onto_search / onto_similarity work, and onto_align automatically uses embeddings as a 7th signal.
- Cache, don't re-parse — when juggling several
.ttl files, use onto_cache_list / onto_repo_load to leverage the on-disk N-Triples cache.
Tool Quick Reference
Core ontology
| Tool | Purpose |
|---|
onto_status | Server health and loaded triple count |
onto_validate | Check OWL/RDF syntax (file or inline Turtle) |
onto_load | Load into Oxigraph triple store |
onto_stats | Class/property/triple counts |
onto_lint | Missing labels, comments, domains |
onto_query | Run SPARQL queries |
onto_diff | Compare two ontologies |
onto_save | Persist to file |
onto_convert | Format conversion |
onto_clear | Reset the store |
Cache and multi-file loading
| Tool | Purpose |
|---|
onto_unload | Drop the active (or named) ontology from memory |
onto_recompile | Re-parse the source, ignoring the cache |
onto_cache_status / onto_cache_list | Inspect compile cache |
onto_cache_remove | Drop a cached entry |
onto_repo_list | Enumerate .ttl/.owl/.nt/.rdf/.nq/.trig/.jsonld files in [general] ontology_dirs |
onto_repo_load | Load by name / relative path / absolute path inside a repo dir |
Remote and lifecycle
| Tool | Purpose |
|---|
onto_pull / onto_push | Fetch from / send to a remote URL or SPARQL endpoint |
onto_marketplace | Browse / install standard ontologies |
onto_import | Resolve owl:imports |
onto_version / onto_history / onto_rollback | Snapshots |
onto_plan / onto_enforce / onto_apply / onto_lock / onto_drift / onto_monitor / onto_monitor_clear / onto_lineage | Terraform-style lifecycle |
onto_lint_feedback / onto_enforce_feedback / onto_align_feedback | Self-calibrating suppression |
Data pipeline (file + SQL)
| Tool | Purpose |
|---|
onto_map | Generate mapping from data + ontology |
onto_ingest | File → RDF (CSV/JSON/NDJSON/XML/YAML/XLSX/Parquet) |
onto_sql_ingest | SQL SELECT against Postgres or DuckDB → RDF (same mapping format) |
onto_import_schema | Postgres or DuckDB schema → OWL |
onto_shacl | SHACL validation |
onto_reason | RDFS / OWL-RL inference |
onto_extend | File-based: ingest + SHACL + reason |
onto_dl_check / onto_dl_explain | DL tableaux subsumption / unsat explanation |
Clinical and alignment
| Tool | Purpose |
|---|
onto_crosswalk / onto_enrich / onto_validate_clinical | ICD-10 / SNOMED / MeSH crosswalks |
onto_align | Cross-ontology alignment (uses embeddings if loaded) |
Embeddings and semantic search
| Tool | Purpose |
|---|
onto_embed | Generate text + Poincaré structural embeddings for all classes |
onto_search | Natural-language query → most-similar classes |
onto_similarity | Cosine + Poincaré distance between two IRIs |
SQL Backbone Notes
onto_sql_ingest and onto_import_schema accept any of:
postgres://user:pass@host/db (requires the postgres Cargo feature)duckdb:///path/to/file.duckdb, :memory:, or a bare *.duckdb / *.ddb file path (requires the duckdb Cargo feature)
DuckDB is wired in as a data integration backbone, not as a SPARQL parser:
its httpfs, parquet, csv, json, postgres_scanner, iceberg, and
delta extensions let one SQL query federate over remote files, object
stores, and other databases — all of which then flow into the same mapping +
SHACL + reasoning pipeline used for plain CSV/Parquet inputs. See
docs/data-pipeline.md for full examples.
