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_dlp_boundary SECOND, and read it before trusting anything onto_reason returns. onto_defects asks whether the declarations contradict each other; this asks a different question the rest of the pipeline never answers: which of your axioms the rule table can actually see. A certificate from onto_reason is a sound proof about the axioms the rules read and says nothing at all about the ones no rule fires on, so a green certificate over an ontology whose TBox is half invisible is true and misleading at once. The report keeps three failures apart and you act on each differently, because they are fixed in three different places. An axiom outside_the_fragment (a disjunction in the consequent, an existential in the head, a cardinality restriction, a negation in the antecedent) is not Horn, and only a rewrite of the ontology helps. An axiom inside_the_fragment_but_a_rule_is_not_implemented (owl:hasKey, owl:propertyChainAxiom, owl:FunctionalProperty) is Horn, has an OWL 2 RL rule, and is invisible only because this engine does not run it, so nothing about the ontology is wrong. And an axiom partially_inside_the_fragment is half seen, and the question is which half you needed. not_fully_seen_by_the_rule_table carries all three counts and never adds them 7a. onto_dlp_boundary answers that question for the ONTOLOGY. onto_trace_label answers it for one TRACE: hand it a reasoning trace that claims inference steps and each step comes back entailed, not_entailed or outside_the_fragment, with the same two dimensions kept apart, so a step nobody could ever derive is never reported as a step this graph happens not to support. It also reports the LOCAL answer separately, over the premises the step itself cited, so a step whose reasoning is valid over triples the graph does not hold is visible as exactly that rather than as sound. Over a rule table YOU supply, a checked step earns entailed_under_supplied_rules_checked and the family word carries the same qualification, never the bare word, and the report carries the table digest
3. Call onto_reason with profile rdfs or owl-rl to materialize inferred triples (transitive subclass chains, domain/range propagation, equivalentClass expansion). The profile decides how much of the rule table runs: rdfs evaluates 6 of the 29 rules, owl-rl 17 and owl-rl-ext all 29, and onto_dlp_boundary reports which
4. Call onto_stats again to verify inferred triple counts are reasonable