A Revision Lands: The Open Data Model on Working Terms

Standards adoption is usually described in terms of intent: we align with the Open Data Model, our partners can integrate faster. Those sentences are cheap. The useful question is narrower and more revealing: when a revision to an entity document is published on an ordinary weekday morning, what does your team actually do?

Here is that morning, twice.

Before

10:40. Someone notices the revision in a newsletter, or a partner mentions it on a call.

10:55. A ticket is created. It says "review ODM changes and update schemas." It is sized small, because everyone remembers the last one as mostly copy-paste.

Two days later. An engineer opens the revised entity document alongside the schema file in the repository, reads both, and starts editing. The YAML blocks go in first. The cross-references need adjusting, because the pointers in the document assume a context the standalone file does not have. The practice column has nowhere to live, so it is dropped, as it was last time. Nobody transcribes the sample object, because there is no obvious place to put it.

That afternoon. The pull request goes up. The reviewer's actual assignment is to compare a Markdown document against a JSON file by eye, so they do what every reviewer does under those conditions: confirm the diff looks plausible and approve.

Six weeks later. A payload fails validation in an integration test for reasons nobody can explain, and the investigation ends at a status code that was transcribed as a number instead of a string.

After

10:40. The revision is published.

10:42. A pipeline step posts the revised Markdown, unmodified, to POST /graph/transform/odm/convert/{projectId} at https://coremodels.example.com. Back comes a JSON Schema 2020-12 document: supporting types under $defs, cross-references rewired so they resolve inside the file, the entity-purpose paragraph as the description, the practice level on each property as an x-odm-practice annotation, and the standard's sample object attached as examples. Alongside it, a lossiness ledger — empty in the clean case, which is now a recorded fact rather than an assumption.

10:43. The pipeline diffs that schema against the one it produced from the previous revision. Both artifacts came out of the same deterministic function applied to the same kind of source, so the diff contains the semantic change and nothing else. No formatting noise. No reviewer fatigue.

10:50. The change turns out to be real: one field gained an enum value, and an optional field moved from COULD to SHOULD. An engineer calls POST /graph/transform/odm/import/{projectId} with dryRun set to true and reads what would happen — a summary counting the types, elements, and taxonomies the entity would contribute, plus the ledger of anything the governed model could not hold exactly. Dry runs need only Viewer access, so this is not a privileged act; anyone on the team can ask the question.

11:05. The summary and the ledger go into the pull request as evidence. The reviewer is no longer comparing prose to JSON by eye; they are reading a machine's account of what the change means.

11:15. Someone with Admin on the project runs the same import for real. The schema is written into the project through the normal profile layer, and the converted artifact in the repository keeps the origin on the record — x-odm-source naming the standards repository, the entity-derived $id — so the origin question always has an answer. Because a re-import upserts rather than duplicating, running it again after the next revision refines the same governed types instead of forking them.

11:20. The chore is done. The interesting part starts.

What the team can do that it could not before

Once an entity is governed rather than transcribed, the standard stops being something you comply with and becomes something you can draw from.

Hand every downstream team the same meaning in their own format. The governed model exports as SQL DDL for the warehouse — Postgres by default, MySQL or SQL Server on request — as Avro for the streaming registry, as an ODCS data contract for a team that works contract-first, as LinkML or OWL for the semantics group, and as JSON-LD, ShEx, Protobuf, or a Synapse draft-07 profile besides. Each export carries its own ledger of what that target could not represent exactly. Nobody re-reads the entity document to produce any of them.

Answer conformance questions with a command instead of an opinion. "Does our order payload still satisfy the standard?" becomes a validation run against a real JSON Schema 2020-12 document. The practice annotations let you ask the sharper follow-up too: of the fields that failed, which does the standard say MUST be there, and which does it merely suggest?

Convert the catalog, not the entity. The converter accepts a list of entity documents in one call and returns a bundle keyed by kebab-cased entity name. Files that are not entity documents are skipped as exactly that; a file that fails to convert is named in the ledger as a structural drop while the rest of the bundle completes. Onboarding every entity you care about is one request and one report.

Onboard a partner in their vocabulary. When an integration partner needs the customer entity as Avro, the answer is an export produced in seconds, traceable to the same governed model your API team reads. The conversation stops being "send us your schema" and becomes "which format would you like it in?"

Let assistants work from the standard rather than around it. The same conversion is available to AI agents through our MCP server, so an assistant asked about an entity reads the converted schema — required lists, enums, practice levels, worked example — instead of reconstructing the standard from memory.

The part that compounds

One morning saved is a small win: a few hours of transcription, one class of bug retired. The win that compounds is that the cost of the next revision no longer depends on how much anyone remembers about the last one, or on whether that person is still on the team.

That is the difference between adopting a standard and aligning with one. Adoption means the standard is wired into how the system is built: read by a converter, reviewed as a diff, imported behind a dry run, exported into every format that needs it, stamped with where it came from. Alignment means somebody once typed it out carefully, and everyone has been hoping ever since.

To see the convert and import calls end to end, start with the schema transform quickstart in the CoreModels docs.