Two Numbers, One Word

Someone puts a slide on the screen: revenue for the quarter, from the finance dashboard. Someone else has the same metric open in a notebook, sourced from the warehouse, and the figure differs by a little under two percent. Both are right, in the sense that each number is exactly what its definition says it is. One nets out returns; the other does not.

The meeting now spends forty minutes on archaeology — not because the difference is hard to find, but because the two definitions cannot be put side by side. One lives inside a BI tool's semantic layer, in that tool's dialect. The other lives in a transformation project as SQL and a comment. There is no artifact both parties can open, diff, and agree on.

That is the gap Apache Ossie exists to close, and it is worth being precise about what the gap costs before talking about closing it.

The bill arrives three ways

At migration time. When an organization adds or replaces a BI tool, the infrastructure work is estimable. The semantic work is not. Hundreds of metric definitions, join paths, filters, and business names get re-implemented by hand in a new dialect, usually by people who were not in the room when the originals were written. Every re-implementation is a fork where a number can change.

At the edges of the tool. Semantic definitions are needed well outside whatever product stores them. The transformation framework wants to know which columns are keys. A new analyst wants to know what the team means by an active customer. The knowledge exists and has been written down carefully; it simply cannot be handed over. What gets handed over instead is a screenshot, a link to somebody's workspace, or an export in a shape exactly one product can read.

At the point where an assistant answers a question. An AI agent asked what revenue was last week, against a bare warehouse, has no option but to infer an answer from table and column names. Nobody reading the fluent result can tell which parts were read and which were guessed.

What the format actually gives you

An Ossie semantic model is a plain document — YAML or JSON — with a small, legible shape. A model has a name and a list of datasets. Each dataset points at a physical source, declares its fields, and may declare a primary key and unique keys. Relationships between datasets are first-class and carry the columns they join on. Metrics carry expressions tagged by dialect, so an ANSI SQL form can sit beside engine-specific forms without either being privileged. Vendors get a labeled home for their own data in named custom extensions. And an ai_context block — instructions, synonyms, examples — can hang off the model itself or off any dataset, field, relationship, or metric inside it.

It is a young specification, on the 0.1 line, and 0.1.1 is the release we target. The shape is right; on its own it is not enough, for practical rather than philosophical reasons.

Four things that happen the moment your semantic model becomes a file

Two consumers want two serializations. People review YAML in pull requests. dbt ingests OSI semantic models as JSON. Without a single upstream source, a team maintains two files and a conversion script somebody wrote in an afternoon.

The format deliberately carries no field type system. Ossie can say that a field is a time dimension. It cannot say whether an amount is an integer or a decimal with two places. That is a defensible scope decision — types belong to the systems that store the data — but it means the document cannot drive DDL, validators, or a registry on its own. It has to compose with the formats that do carry types, and something has to hold both views in one place.

Real documents are untidy. Files in circulation carry keys the specification never defined. They use a single-object shorthand where a list of models is expected. They write a bare string where a dialect list belongs, or give a primary key as a scalar instead of an array. Some declare a version number that was never a published release. A strict parser rejects precisely the people who adopted earliest.

And a file in a repository is not a governance process. "Revenue now excludes returns" is a business decision. If it lands as a two-line diff that nobody was required to read closely, portability has bought faster propagation of unreviewed meaning.

What we built, and where the line is

CoreModels is our schema governance platform at ARAMAI. It implements Ossie in both directions, alongside eleven other format keys behind one dispatch: osi is the spec's YAML serialization, osi-json the identical model as JSON — the form dbt ingests. Either serialization is accepted under either key on the way in, because JSON is a subset of YAML and one parser honestly reads both.

The reader is deliberately forgiving. Nothing is bound to a fixed class on the way in, so a key we have never seen does not stop the parse — it is kept as written and put back where it came from on the way out. Single-object models, scalar primary keys, and bare-string expressions are tolerated. Documents stamped with the phantom 1.0 version are accepted and normalized to 0.1.1, with the normalization written into the change report rather than applied silently. Published versions round-trip untouched.

In the intermediate model, a dataset becomes a type, a field becomes an element, primary-key fields arrive marked required, and a field flagged as a time dimension arrives typed as a date-time — the one type distinction the format carries. Relationships become structured relations with their join columns attached, and each metric becomes a component linked to the datasets its expression names. Descriptions, synonyms, AI instructions, per-dialect expressions, unique keys, and vendor extensions all ride along and come back out the other side.

Every call returns an honest ledger of what the translation could not carry exactly — how you find out that a controlled value list had no home in the target, or that a primary key names a column no field matches. Importing into a project is an administrative act; exporting is a read.

That is the shape of the need. Meaning finally has an interchange document. What it still needs is a governed home, a translator that admits what it dropped, and a reader tolerant enough to accept what a young ecosystem actually produces.

To try an Ossie import or export against your own model, start with the transform quickstart in the CoreModels documentation.