The Confession at the Top of the File: Governance Through the OWL Round Trip

Open an ontology exported from CoreModels and, before any prefix declaration, you may find something unusual: a block of comment lines beginning # lossiness:. Each one names a kind of change, the exact path in the model where it happened, and a plain-English explanation of what the export could not carry. Comments are valid Turtle, so the file still loads cleanly into GraphDB or Protégé — but anyone who opens it reads the confession first.

That header is our governance philosophy in miniature. A schema translation you can trust is not one that claims to be perfect; it is one that tells you precisely where it is imperfect, in the artifact itself, where the reviewer will actually look.

Four ways a translation can bend

Every transform response from CoreModels — over the REST API or the MCP tools — carries a lossiness ledger alongside the result. Each record has one of four kinds, and the OWL round trip produces concrete examples of all of them.

A StructuralDrop means something had no home in the target. OWL has no construct for a curated view, so a component defined in the governed model is not exported — and the ledger says so, naming the component. An element that no type owns is exported without a domain, and that is recorded too.

A SemanticNarrowing means meaning was reduced. A governed relation whose group semantics OWL cannot express is narrowed to rdfs:seeAlso, with a record naming the relation and the group. On import, a class with multiple parents is narrowed to the single parent our model holds; a label carrying language tags keeps its first form and the narrowing is written down.

A TypeApproximation means a close-but-not-exact type stood in. Rich text becomes xsd:string on export; an object property that arrives without a range is approximated as a string on import. Both are recorded at the exact element.

A ConstraintRelaxation means a rule could not be enforced. A minimum-items bound above one has no OWL carrier beyond a minimum-cardinality restriction, so the bound is relaxed — honestly, on the record.

None of these events is an error, and none is silent. That distinction is the whole design.

The import side never bluffs

Governance cuts both ways: an importer that fails on anything unfamiliar is unusable, and an importer that silently discards the unfamiliar is dangerous. Our OWL decoder does neither. Well-formed triples outside the schema vocabulary it understands — annotation properties from a vocabulary we don't model, metadata assertions, provenance triples — are counted and reported as a single summarized lossiness record. Your ontology is never rejected for being richer than our model, and you are never left wondering whether the richness quietly vanished. The count tells you.

Hard failure is reserved for documents that are actually broken — an unclosed IRI, an unterminated literal — and those come back as structured errors with a line number, not an exception and not a half-imported project.

This is why we insist on a habit that sounds pedantic until it saves you: success: true does not mean "nothing changed." It means the operation ran. The ledger is the list of what changed, and reading it is the review step — an empty ledger is a clean conversion; a populated one is a checklist of exactly what to verify on the other side.

Meaning changes pass through people

The OWL surface obeys the same authority rules as every other write path into a governed model. Exporting an ontology is a read — any project viewer can do it, over the API or the export_owl tool on our MCP endpoint. Importing one writes Types, Elements, and Taxonomies into the project, so it requires the project's admin role, and it only ever happens because someone explicitly asked for it — there is no background process rewriting your model because a Turtle file changed somewhere.

When an ontology needs to be mapped onto an existing project rather than simply imported, the mapping endpoints are built around a stronger contract: dry-run first. A dry run shows the plan — the explicit list of operations — together with the full ledger, touching nothing; the project changes only when someone asks again with the dry run turned off. Even when the mapping is proposed by AI, the proposal passes the same validation gate as a hand-written mapping, with at most one repair attempt; a plan the gate rejects is rejected, whatever confidence the proposer attached to it. The gate never trusts self-reported confidence, and it never relaxes for anyone.

Drift leaves evidence

Every construct imported from OWL is stamped with provenance: the source format and the subject IRI it came from. Six months later, when someone asks why the project contains a type nobody remembers creating, the answer is on the node — it arrived from that ontology, as that IRI, through that import. Combined with the ledger from the original import, you can reconstruct not just what the model says but how it came to say it, and what the translation admitted it could not preserve at the time.

That is what we mean by drift as evidence. Ontologies and operational models will diverge — teams edit them, standards evolve, vocabularies get replaced. A governed round trip does not pretend divergence away; it makes divergence visible, at import time in the ledger, over time in the provenance, and at export time in the comment block at the top of the file.

Review-and-deploy, not export-and-hope

Put the pieces together and the workflow that emerges looks like software delivery, because it is. The ontology is generated from the governed model, not hand-edited. Its ledger travels inside it, so the person reviewing the artifact — in a pull request, in a data-sharing handoff, in a triple-store deployment — sees the losses inline without needing access to our API response. Changes to meaning go through roles and dry runs. And when the reasoner on the receiving end checks the cardinality axioms, it is checking constraints the governed model actually asserts, because those axioms are how we carry required and single-valued through the translation.

Trust, in schema work, is not a feeling. It is a ledger, a role check, a dry run, and a provenance stamp — every time, on the record.

The transform section of the CoreModels docs covers the ledger format, the four kinds, and the dry-run contract in detail.