Count the JSON Schemas You Used Today Without Noticing

Before lunch you probably touched five of them. The request body in an API definition is JSON Schema. The configuration file that failed CI with a helpful message was validated against JSON Schema. If your team runs a schema registry, some of the subjects in it are JSON Schema rather than Avro. If you asked a model for structured output, the shape you asked for was JSON Schema. And if you used an AI assistant with tools, every one of those tool contracts — the argument names, the types, the required list — was JSON Schema too.

That is a remarkable position for a format to reach. It is also the source of the most common misunderstanding about it: ubiquity is not interoperability.

Everybody speaks it. Nobody speaks all of it.

"JSON Schema" on two systems rarely denotes the same set of keywords. One platform models a documented subset of draft-07 in its REST objects. A registry parses JSON Schema subjects shallowly, reading properties, required, enums, and formats — enough to know the shape, not enough to reconstruct a deep document. A code generator supports the structural keywords and quietly ignores the conditional ones. A validation library implements one dialect thoroughly and another partially.

So the format that everyone can read becomes, in practice, a family of overlapping dialects held together by optimism. That is fine when JSON Schema is doing its actual job — deciding whether a document conforms, right here, in this service. It stops being fine the moment somebody treats the file as the authoritative definition of a business concept and hands it to a system that reads a different subset.

Where we put it: one key among thirteen

In the CoreModels transform surface, jsonschema is a format key — with sia accepted as an alias — alongside ShEx, Avro, JSON-LD, SQL DDL, Apache Ossie semantic models in YAML and JSON, OWL, LinkML, Protocol Buffers, Bitol ODCS data contracts, MACH ODM entity documents, and the Synapse profile. Every format converts through a neutral internal model of Types, Elements, Taxonomies, and references. JSON Schema is a spoke on that hub, exactly like the others.

The architecture is the neutrality. If JSON Schema were the internal model, every other format would inherit its blind spots: no native inheritance construct, dialect fragmentation, conditional combinators that no relational or ontology language can express. Translating through a format-agnostic model means no single standard's worldview becomes everyone else's ceiling. Your model is not "a JSON Schema with extras." It is a model, of which JSON Schema is one faithful projection.

What it composes with, concretely

The Synapse profile (Sage Bionetworks). Synapse's JsonSchema REST object models a documented draft-07 subset. We implement that subset as an encode-only output profile: $schema declares draft-07, $defs becomes definitions with $ref pointers rewritten, and the $id follows the documented registered-schema form composed from an organization, a name, and a semantic version. Every keyword outside the documented field set is stripped with an explicit lossiness record naming the keyword and the path — never silently. Where the public documentation is genuinely silent about a behavior, we record that uncertainty as lossiness rather than invent wire semantics. And it is encode-only for a principled reason: a Synapse schema is plain draft-07 JSON Schema, so you re-import it with the jsonschema key. There is no proprietary round trip, because there does not need to be one.

Schema registries. A Confluent Schema Registry subject export can contain Avro records, JSON Schema, and Protobuf side by side. Avro records parse fully; JSON Schema subjects parse at depth one — properties, required, enums, formats; Protobuf subjects are counted and reported rather than silently dropped. That mixed reality is the norm in streaming estates, and the honest thing is to say which parts were understood in full and which were not.

Documentation standards. MACH Alliance ODM entity documents are Markdown, not machine artifacts. We convert them into formal JSON Schema 2020-12, carrying $defs, a per-property practice annotation derived from the MUST/SHOULD/COULD table, and examples from the sample object. That direction is one-way by design: the entity document is authored prose, and generating prose back from a model would be a fabrication.

The mapping engine. When you map a SQL table onto a target, the most natural way to say what you are mapping toward is a JSON Schema hint. Its ubiquity makes it excellent for that role — expressing an expectation to a machine — which is different from being the place your organization's meaning lives.

Agent tooling. The tool contracts on our MCP server are themselves JSON Schema documents, with typed arguments and patterns on identifiers — and on the transform tool, a closed additionalProperties, so an invented argument is rejected rather than ignored. The format that describes payloads now also describes capabilities.

Why neutrality is a feature and not a posture

We implement other people's specifications. We do not own JSON Schema, ODCS, LinkML, Apache Ossie, ODM, or the Synapse profile, and we do not ask you to adopt an interface definition language of ours in exchange for tooling. Those specifications will outlive any single vendor's product decisions, including ours, and a model that can only leave through a proprietary door is not governed — it is captured.

The practical test is simple: the exit is the entrance. The same governed model that ingested your JSON Schema exports SQL DDL for three vendors, Avro, proto3, LinkML, OWL, ShEx, JSON-LD, ODCS, Ossie semantic models in either serialization, and JSON Schema again. If you decide tomorrow that CoreModels is not for you, you leave with your model expressed in standard formats and an honest report of what each one could not hold exactly. That is the only version of neutrality that means anything.

What this leaves JSON Schema doing

Its actual job, extremely well. Your services keep validating payloads against JSON Schema, because that is the job it was built for. Your repositories keep a JSON Schema file, because tooling expects one there.

What moves is authorship. The file becomes a generated projection of a model that also knows what the fields mean, which concepts they bind to, and what they look like in six other formats — instead of being the fragile original that five other artifacts were once hand-copied from.

The full format list and the options for each are in the schema transformation guide in the CoreModels docs.