One Model, Every Downstream Format: What Governed LinkML Actually Buys You

The clearest sign that a team has adopted this is what has gone missing from their repository. The four hand-maintained schema files that used to shadow the LinkML model — a DDL script, a JSON Schema, an Avro subject definition, a catalog entry — are no longer there. Not stale, not deprecated, not marked "regenerate me." Gone, because they are outputs now.

What follows is the after-state: the work a team does on the days the model changes.

The model changes

A curator merges a pull request against the LinkML schema. Two things move: an enum gains a permissible value carrying a meaning URI that points at the ontology term it was chosen to represent, and a slot that was optional becomes required: true.

Before, that merge started a fan-out: four tickets, four teams, four hand-written edits in four dialects, each reviewed by someone whose only check was reading the YAML themselves. Elapsed time to a consistent estate: days, sometimes never.

After, the merge is followed by one call: post the LinkML document to the schema import endpoint on the governed project. The class becomes a governed type; the slot a governed element carrying its new required flag; the enum a governed taxonomy whose terms are the permissible values; and the meaning CURIE is expanded through the schema's declared prefixes into the graph's semantic-mapping layer. Import writes at Admin role. Running it twice does not double anything — the writer snapshots what already exists, so a re-import upserts rather than duplicates.

The review that replaced proofreading

The import response carries a lossiness array. On this change it has two entries: a class declaring mixins had the names preserved for re-export but the mixin slots not merged in, and a class referencing top-level slots: had them flattened into inline attributes.

That is the whole review: a short list of the places where the governed model is a normalization of the file rather than a mirror of it, and a decision on whether each is acceptable. It takes about ninety seconds, and the things you might have missed are printed in front of you.

The estate catches up before lunch

Four exports: the same endpoint, a different format value, all at Viewer role.

• jsonschema for the services that validate request bodies
• sql for the warehouse, with vendor set to postgres, mysql, or sqlserver
• avro for the schema registry
• odcs for the catalog, as a Bitol Open Data Contract Standard contract

The same model also exports as OWL Turtle, ShEx shapes, JSON-LD, proto3, an Apache Ossie semantic model in YAML or JSON, the Sage Bionetworks Synapse draft-07 profile — and as LinkML, back out again, for the curators.

Each call returns its own ledger, and they differ honestly. The SQL export reports where a controlled list had no inline enum construct to be enforced by. The LinkML export reports what LinkML itself cannot hold: collection bounds, because multivalued carries no item bounds; the distinction between null and absent; a term hierarchy, because permissible_values are flat. The team reads four short lists instead of comparing four large files.

The question that used to take a day

An analyst working in an MCP-connected assistant asks what the model says about a field. The assistant calls export_linkml against the project over the read-only MCP endpoint and gets the governed model back as LinkML YAML: ranges as named types, enums as permissible values with their meanings, required and multivalued stated rather than implied. The export can be scoped to a space, or to specific type node ids, when the whole model is more than the question needs.

Before, someone pasted a fragment of uncertain age into a chat window and hoped. After, the assistant reads the governed model — and everyone can see which project it read.

The partner mapping that stays reviewable

A partner sends a schema in another format and wants to know how it lines up. The team uses the stateless map endpoint: their format in, LinkML out, mapped against the project's own schema as the target hint. Nothing is written; that endpoint scopes authorization only, so every call is inherently a dry run.

Back comes the produced schema, the full lossiness ledger, and the plan — the executed mapping as a replayable artifact. The plan is what gets attached to the review. Once approved, it is replayed through the plan-execute endpoint: same plan, same source, same output, and the replay passes the identical validation gate it passed the first time. Stored plans get no shortcut.

Before, a mapping lived in one person's head and had to be re-derived whenever it was questioned. After, it is an artifact you can diff, attach to a ticket, and rerun.

The estate gets checked against the model, not against memory

Because the model is governed rather than filed, other tools can compare themselves to it. Vendor artifacts — a dbt manifest, warehouse information-schema rows, registry subjects — go to the audit surface, which reports coverage, drift, and conformance findings against the governed types and taxonomies, with codes such as field-type-drift, enum-narrowed, and field-unmapped. The audit writes nothing to the governed model, and in CI a non-zero errorCount fails the build.

What durably changed

The file stays where it belongs. Curators keep authoring LinkML in the tooling they know, in the repository they already review. Nothing asks them to move into a UI or learn another modeling language: the governed model sits downstream of their file, it does not replace it.

Review changed shape. From checking a translation to reading a ledger — a smaller task with a much better failure mode.

Disagreements became answerable. When the warehouse and the model differ, there is somewhere to look: the governed model, the lossiness records from the export that produced the DDL, and the audit findings from the estate. "Which one is right" stopped being decided by seniority.

Exports stopped being bespoke. Emission is deterministic — the same model produces the same YAML in the same key order — so a LinkML export can be committed, diffed in a pull request, and re-decoded exactly. An export is not a one-way trip, which makes it safe to depend on.

None of this required abandoning LinkML or trusting a converter on faith. It required one governed model, a projection for every format that needed one, and a ledger attached to every projection.

The transform quickstart in the CoreModels documentation walks the first import and export end to end.