A Tuesday With a Governed Semantic Model

The clearest way to describe an after-state is to walk through an ordinary day in it. Nothing dramatic happens on this Tuesday; that is the point. Here is the day, with the before-state noted each time, for a team whose Apache Ossie semantic model is a projection of a governed graph rather than a file inside one tool.

09:10 — "Can I get the model in the form dbt reads?"

An analytics engineer needs the semantic model as JSON, the serialization dbt ingests. Twenty minutes later an analyst asks for the same model as YAML, because YAML is what people read in a pull request.

Before: two files, a conversion script somebody wrote in an afternoon, and an unpleasant discovery months later that the script was skipped once.

After: two exports of the same governed model, one call each. The format key osi emits the spec's YAML; osi-json emits the identical model as JSON. These are not two hopeful code paths — the JSON document is derived from the same emission as the YAML, and our tests decode both back to the same structure to prove it. Where the model carries no version of its own, exports are stamped with spec version 0.1.1; a published version already on the model is re-emitted exactly as it arrived.

10:30 — A partner sends a semantic model that nothing will open

A collaborating team shares their Ossie document. It carries a key their platform adds that the spec does not define, the semantic model is a single object where a list is expected, one expression is a bare string instead of a dialect list, one dataset gives its primary key as a scalar, and the whole thing is stamped version: "1.0" — a release the specification never published.

Before: an afternoon of hand-editing somebody else's file until your parser stops complaining.

After: it decodes. Our reader walks a generic object graph defensively instead of binding to rigid classes, so an unrecognized key cannot break the parse; it is preserved verbatim and re-emitted. The shorthand, the scalar key, and the bare-string expression are all tolerated — the last is read as the ANSI SQL dialect. The phantom version is normalized to 0.1.1 and the normalization is written into the change report, so you see what was adjusted rather than wondering.

11:45 — "Add a metric" and "rename that field"

Before: a rename is a fan-out. Someone updates the BI tool's semantic layer, someone updates the transformation project, someone means to update the wiki. The number of places that must change is the number of places that can be forgotten.

After: the change happens once, and every serialization reflects it on the next export. A new metric carries its description, its per-dialect expressions, and its synonyms, and exports with all of them. Metrics are not free-floating strings in the intermediate model either: each is linked to the datasets its expression names, so a reviewer can see that a revenue metric touches the web sales dataset — and can see when a proposed metric touches a dataset nobody expected.

13:20 — "What does this field actually mean?"

Before: ask the person who wrote it, and if they are out, read the SQL.

After: the answer travels inside the document. The dataset's schema-qualified physical source. The description on the field. The synonyms a business user or an assistant would actually say. The AI instructions written to steer interpretation, the worked examples, the unique keys, and the join columns on each relationship. All of it survives a trip through our engine and comes back out the other side.

One detail matters more than it sounds: original names are preserved as labels while internal node ids are normalized to alphanumerics. A dataset named web_sales still reads as web_sales even though the id underneath is camelCase, so the model still speaks your table names.

14:40 — "We're standing up something new and need the schema"

This is the request that shows what the after-state is really for. A new service wants JSON Schema. The warehouse team wants DDL. A research collaborator wants LinkML. A downstream consumer wants an ODCS data contract.

Before: four separate translations from whichever artifact happened to be nearest.

After: four requests answered from the same place your Ossie document comes from. Thirteen format keys share one dispatch, so choosing a target is choosing a word in the request body rather than choosing a toolchain, and the four answers agree with each other because they were produced from one model rather than four artifacts of different ages.

The split of responsibilities is why the arrangement pays. Ossie contributes meaning the structural formats have no slot for: metrics, join semantics, synonyms, machine-readable guidance. Those formats contribute the type system Ossie deliberately does not carry. Held in one model, they stop competing to be the single true description of a table.

16:15 — Reading the change report

The after-state asks one thing of you in return: read the ledger.

Every response lists what the translation could not carry exactly, and Ossie exercises it in both directions. Importing a document produces a single summarized note: the format has no field type system, so fields arrived as strings, or as date-times where the document marked a time dimension. One note for the schema, not one per field. Exporting a governed model containing a controlled value list produces a note that Ossie has no construct for one, so it was left out rather than smuggled in under a private key. Inheritance and non-metric components get the same treatment.

The ledger is equally frank about the governed store's own boundaries. Writing a semantic model into a project persists datasets as governed types and fields as elements with their required marks; relationships and metrics do not travel that path, and the ledger says so instead of letting you assume they arrived. You always know which part of your model is governed structure and which part lives in the document.

The one-sentence version

Nothing about your tools has to change. dbt still reads its JSON, analysts still read YAML, the warehouse still runs DDL. What changes is that none of those files is the original any more — the governed model is, and the files are views you regenerate at will.

To try the round trip on your own model, the transform quickstart in the CoreModels documentation walks through a first import and export end to end.