LinkML Doesn't Need Us to Generate JSON Schema

Start with the awkward fact; it is the honest way in. LinkML already ships a generator toolchain. If your entire need is "turn this model into a validation artifact," the project's own tooling does that, maintained by the people who write the specification, and you should keep using it. A product that opens by claiming otherwise is selling something.

So what is a neutral hub for, and where does LinkML sit inside one?

What LinkML is good at, and where its remit ends

LinkML is a modeling language for people who care that terms mean something. Classes inherit. Slots declare cardinality and optionality as facts rather than conventions. Enums are controlled lists whose members can carry a meaning — a compact URI over declared prefixes that ties a permissible value to a defined term rather than to a string that resembles one. Classes and slots carry class_uri and slot_uri bindings of their own. That design puts LinkML next to the semantic-web vocabularies its models reach for — RDF and RDFS, OWL, SKOS, Dublin Core terms, PROV, schema.org, the OBO family, biolink — which are the prefixes our coder seeds by default, so a CURIE resolves even when a document leaves the declaration implicit.

Where LinkML's remit ends is equally clear, and not a criticism. LinkML describes a model; it does not describe your estate. It has nothing to say about what the warehouse contains this morning, which dbt models claim a contract, what the schema registry accepted last week, or whether the term someone bound in March is still the one the working group prefers. A model is a statement of intent; governing an estate means continuously comparing intent against reality, and that comparison needs a home outside any one format's toolchain.

A hub is only credible if it privileges nobody

CoreModels converts between formats through a neutral intermediate representation. LinkML is one coder against that IR, alongside JSON Schema, ShEx, Avro, JSON-LD, SQL DDL, OWL, Apache Ossie (formerly OSI) in YAML or JSON, proto3, Bitol ODCS contracts, MACH ODM entity documentation, and the Sage Bionetworks Synapse draft-07 profile. The IR is not LinkML-shaped, and not JSON-Schema-shaped either. If it were, neutrality would be marketing: one format's idioms would survive translation better than the rest, for structural reasons nobody documented.

Two choices keep that honest.

The coders are independent implementations. Where two coders need the same trick — a defensive walk over a loosely typed document, an identifier sanitizer — it is reimplemented rather than shared. That looks like duplication and is insulation: a change made to suit LinkML cannot quietly alter how the OSI or ODCS coder behaves.

The asymmetries are published rather than smoothed over. The decode list and the encode list differ. odm decodes only, because ODM entities are authored documentation and there is no honest way to generate prose back out. synapse encodes only, because its output is plain draft-07 JSON Schema — try to decode it as synapse and the error tells you to use jsonschema. sia is an alias for jsonschema; proto for protobuf. LinkML happens to be a full citizen in both directions — a property of the format, not a favor we did it.

Composition is where the value actually is

The reason to put LinkML on a neutral hub is not conversion. It is that everything else on the hub can see it.

The mapsTo carrier is shared. A term bound to a node — whether it arrived as a meaning CURIE in an imported LinkML document, was bound deliberately after an Ontology Lookup Service search, or came in from another format entirely — lives in one place every encoder reads. Export that node as LinkML and it comes back as a class_uri, slot_uri, or meaning. Export it as OWL and it is an ontology assertion. The binding is made once and travels.

The estate integrations point at the same governed model. Warehouse catalogs, dbt projects, streaming registries, and graph databases are audited against it, producing coverage, drift, and conformance findings with stable codes. An imported LinkML model is therefore one your CI gate can enforce against a dbt pull request — not something a modeling language does for itself, and not something a warehouse vendor will do for you, since it would mean reading a competitor's artifacts.

That is the practical case for neutrality. Every vendor here has a schema story, and every one of those stories ends inside that vendor. The interesting comparisons are cross-vendor: does the Avro subject in the registry still agree with the warehouse table that feeds it, and do both still agree with the model the domain experts maintain in YAML? Only something with no stake in the answer can ask that.

What we implement, and what we do not claim

We implement published specifications. LinkML, Apache Ossie, the Bitol Open Data Contract Standard, the MACH Alliance ODM, the Synapse draft-07 profile — we read the specs, pin the versions we emit, and record it when a document has to be normalized to reach one. We are not a standards body, and we have no interest in one of these formats winning. A landscape with several good modeling languages in it is the normal, healthy state of affairs, and the state our design assumes.

Two honest boundaries, in the same spirit. A slot ranging over a user-defined type from a types: section approximates as a string, with the declaration preserved verbatim so nothing leaves the document. And mixins are preserved by name but not merged — a consumer needing the effective slot set of a mixin-using class has to expand it. Both are recorded in the lossiness ledger of any call that hits them, rather than discovered later by someone reading output.

Leaving is an export

The last thing neutrality has to mean is that adoption is reversible. LinkML emission here is deterministic: stable key order, consistent quoting, a prefix header computed from the body so it always declares every prefix the document uses, and class and enum keys precomputed so a reference never rebinds to the wrong target when two nodes share a label. The same governed model produces the same YAML every time — commit-able, diffable in a pull request, and exactly re-decodable.

If that YAML is the only thing you ever take out of the system, the arrangement still worked. That is the standard a neutral hub should be held to.

The transform documentation lists every format key and its options.