A Definition Is a Privileged Change

There is a sentence in our own API documentation that decides how the whole surface behaves: "success: true does not mean 'nothing changed.' It means 'it ran.' Always read lossiness."

That is an unusual thing to write about your own product, and it is the foundation of how we govern Apache Ossie documents in CoreModels: who may change meaning, what happens on the way in, what we admit we could not carry, and how you learn when reality stops matching the definition.

Reads and writes are separated where it matters

Exporting an Ossie document from a project is a read. Viewer access is enough, nothing is written, and the request cannot change what the organization means by anything.

Importing a semantic model is a different act, and it requires an administrator. Datasets land as governed types, fields as elements, primary-key fields with their required marks.

That write is additive by construction. Node creates are upserts by id, and before any edge is written the encoder snapshots the relations already present on the nodes it is about to touch — so re-importing the same model upserts and skips rather than duplicating. Nothing is deleted to make room, which makes a second import of a corrected document safe rather than a gamble.

Mapping a model onto a project's existing schema, rather than simply adding to it, goes through a dry run first: with dryRun: true the plan and its consequences come back for review — Viewer role, nothing written — before the write is committed. And a mapping produced by our AI proposer requires Editor or Admin membership and sends the schema content to the Anthropic API server-side — both stated plainly, because a control you learn about afterwards is not a control. The proposal is then validated by the same gate as every other plan; the gate is never relaxed because a model wrote it.

Four kinds of honesty

Every response carries a ledger whose entries each name one of four kinds, a path pointing at the exact construct, and a plain-language explanation. Ossie exercises all four, and each example below is a decision we would rather defend than hide.

Type approximation. Ossie carries no field type system, so an imported field becomes a string — or a date-time where the document declares a time dimension. We record that once for the whole schema rather than once per field.

Constraint relaxation. Export a governed model containing a controlled value list and the document cannot hold it; the specification has no construct for one. The export succeeds; the ledger says the constraint is not represented.

Semantic narrowing. Type inheritance has no Ossie equivalent, so a parent link is reported as unrepresented. Relations that are not dataset-to-dataset Ossie relationships are reported the same way. Unrecognized keys inside otherwise recognized objects are named individually.

Structural drop. A component that is not a metric has no home in the document, so it is omitted and reported. Subtler: when a dataset's primary key names a column matching no field, the key's composition would change on the next export. That earns a record naming the column, because a governance system that lets a key quietly shrink is worse than one that refuses the file.

The ledger is as frank about our own storage as about the format. Writing a decoded model into a project persists datasets and fields; relationship and metric instances are not written by that path, and each comes back as a declared drop. You are never left to assume something arrived because the call said success.

Including the mistakes that are ours

Early releases of this coder stamped documents with version: "1.0" — a spec release that never existed. The trustworthy response to a shipped mistake is not to quietly stop making it, but to make the correction permanent and visible.

So any document carrying 1.0, including the ones we produced, is accepted, normalized to the published 0.1.1 release, and the normalization is written into the ledger where a reviewer will see it — on the way in and on the way out. Genuine published versions round-trip with no version entry recorded at all, so the ledger distinguishes a real change from a non-change.

The 0.1.1 default is pinned to the schema published at the osi-0.1.1-rc1 tag of the apache/ossie repository, and our JSON output is tested against that schema's constraints: allowed root keys, the required name on a model, the name and source on a dataset, an expression carrying at least one dialect on every field.

Deterministic output is a review control

Our Ossie YAML is written by hand rather than dumped by a serializer: stable key order, indentation, and quoting, with lists in a flow style valid in both YAML and JSON. The JSON serialization is derived from that same emission, which is why both decode back to the same model.

This sounds like an aesthetic preference. It is a governance control. A diff between two exports shows only what actually changed in the model, which is the precondition for review being real rather than ceremonial; a serializer that reorders keys between runs produces diffs nobody reads twice.

We also never extend the format privately. Where the governed model holds something Ossie cannot express, the export leaves it out and says so. A private key would make our exports round-trip beautifully through our own tooling and slightly less like Ossie to everyone else.

Divergence, recorded

A governed definition is worth something only if you find out when reality stops matching it. Because an imported semantic model lands in the same governed graph as the rest of your schema, that graph is what our Schema Audit compares vendor artifacts against — a dbt manifest from an ordinary build, for example. Divergence comes back as structured findings, each with a section, a severity, and a code such as field-type-drift, plus a Markdown report suited to a pull-request comment. In CI, an error count above zero is the fail signal, and recorded runs accumulate into a history and a status badge. Drift stops being folklore exchanged in a metrics meeting and becomes an artifact with a timestamp.

The short version

Portability without process is just faster propagation of unreviewed meaning. What makes a portable semantic model trustworthy is the unglamorous apparatus around it: additive imports behind an admin role, read-only exports, dry-run plans, deterministic output, a ledger that confesses precisely — including about our own past mistakes — and an audit trail that turns divergence into evidence.

The full description of the response envelope and the four lossiness kinds is in the CoreModels transform documentation.