open-ontologies: Instructions file for Claude Code

Open Ontologies

Ontology Engineering Workflow

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

Generate

1. Understand the domain requirements (natural language, competency questions, methodology constraints)
2. Generate Turtle/OWL directly — Claude knows OWL, RDF, BORO, 4D modeling natively

Validate and Load

1. Call onto_validate on the generated Turtle — if it fails, fix the syntax errors and re-validate
2. Call onto_load to load into the Oxigraph triple store
3. Call onto_stats to verify class count, property count, triple count match expectations

Reason

1. Call onto_defects FIRST. A reasoner amplifies whatever the declarations say, so a self-contradicting ontology makes every inference suspect. Fix what it reports before materializing anything
2. Call onto_reason with profile rdfs or owl-rl to materialize inferred triples (transitive subclass chains, domain/range propagation, equivalentClass expansion)
3. Call onto_stats again to verify inferred triple counts are reasonable

Verify

1. Call onto_lint to check for missing labels, comments, domains, ranges — fix any issues found
2. Call onto_enforce with rule pack generic to check design pattern compliance — fix any violations
3. Call onto_query with SPARQL to verify structure:
   • Are all expected classes present?
   • Do subclass hierarchies match the spec?
   • Can competency questions be answered?
4. If a reference ontology exists, call onto_diff to compare

Iterate

1. If any step above reveals problems, fix the Turtle and restart from step 3
2. This loop continues until validation passes, stats match, lint is clean, enforce has no violations, and SPARQL queries return expected results

Persist

1. Call onto_save to write the final ontology to a .ttl file
2. Call onto_version to save a named snapshot for rollback — always version after save