Solving the JSON Schema dialect fragmentation problem with auto-upgrades

TL;DR: JSON Schema has published many dialects with breaking changes, and specs like OpenAPI add their own extensions and constraints on top. Different tools and schemas sit on different dialects, so using a schema you need or plugging it into a tool you need is often hard or impossible. What you really want is to keep one schema and let every tool receive it in the dialect it understands. Sourcemeta finally makes that possible, upgrading any schema on the fly to the dialect a tool expects, through the JSON Schema CLI or the Sourcemeta One registry.
A 2025 OpenProceedings paper calls JSON Schema “the de facto standard schema language to describe JSON data”, with an adoption that is “almost ubiquitous” (OpenProceedings, 2025). Today, it is the one schema language every major AI provider (OpenAI, Google, Anthropic, Mistral, xAI, DeepSeek) has converged on, and the format the Model Context Protocol speaks. It is what every G7 government runs its digital public infrastructure on, and from December 2026 every EU country must run its eIDAS 2.0 digital identity system on it as well. Whatever you are building, you almost certainly depend on JSON Schema, directly or through OpenAPI, MCP, or a cloud service.
Like any healthy standard, JSON Schema evolves. Each new version revisits earlier decisions as the community learns more, rather than keeping them forever. That willingness to break backward compatibility is much of what has kept it from accumulating legacy it could never remove. The price is simply that a schema written for one version may no longer be valid, or may quietly mean something different, under another. Some are easy to spot: in Draft 6 the identifier keyword id was renamed to $id. Others are far more subtle, like how the $anchor keyword accepted colons in 2019-09 but no longer does in 2020-12.
The result is a family of dialects, each with its own set of breaking changes:
JSON Schema is also a building block for other specifications, which embed it to describe their data. So every breaking change in JSON Schema cascades up into whatever is built on top of it. The clearest example is OpenAPI, which embeds JSON Schema to describe the data in an API.
What an OpenAPI document embeds is not a plain upstream dialect but its own variant of JSON Schema, the OpenAPI Schema Object. Each OpenAPI version ties that object to a particular JSON Schema dialect and then extends or restricts it in its own way. OpenAPI has also rebased onto a newer dialect more than once. All of this adds a new dimension to the fragmentation from the previous section:
OpenAPI is not the only one. The Model Context Protocol, the fast-growing standard that wires AI models to tools and also builds on JSON Schema to describe a tool’s inputs and outputs, hit the problem from the opposite direction. Where each OpenAPI version pins a dialect and reshapes it, MCP left its embedded tool schemas without a declared dialect at all. Implementations then ended up “split between draft-07 and 2020-12”, until SEP-1613 (October 2025) “establishes JSON Schema 2020-12 as the default dialect for embedded schemas within MCP messages”.
The flagship API and AI specs are not the only ones to change dialect. For example, format specifications that ship JSON Schemas straight to their users have quietly done the same. glTF, Khronos’s 3D asset format, went from Draft 4 to 2020-12 in 2021. Docker Compose moved from 2019-09 to 2020-12 in 2026. SPDX, the software bill-of-materials standard, went from Draft 7 to 2020-12 with its 3.0 line in 2024. And STAC, the SpatioTemporal Asset Catalog for geospatial data, moved from Draft 6 to Draft 7 in 2020. Whole products migrate too: Confluent Schema Registry, Kafka’s schema registry, added 2020-12 in Platform 7.6.0 in 2024, and OpenMetadata, an open-source metadata platform, moved its entire schema corpus from Draft 7 to 2020-12 in a single 2026 pull request touching 1,324 files.
Pinning this down precisely is close to impossible. Most JSON Schema and OpenAPI use lives inside companies, in private repositories and internal services no one outside can measure. What is public is only a slice, so the best we can do is triangulate from a few imperfect proxies. None is exhaustive or representative on its own, and each looks at a different population, so treat what follows as a rough picture, not a census. The useful part is that the proxies disagree on magnitude but agree on the ranking.
Start with live traffic. The json-schema.org website hosts the meta-schema for each dialect. Its Cloudflare analytics show which of those meta-schemas the world requests most over a trailing 30-day window, and the ranking is telling: Draft 7 leads by a wide margin, Draft 4 is a close second, and 2020-12 only comes third, with Draft 6 and 2019-09 far behind. That Draft 4, whose specification was published back in 2013, still outdraws the current dialect is the sharpest sign of how sticky older dialects can be.
The first surprise is that Draft 7 leads at all. OpenAPI, the single largest consumer of JSON Schema, never used it. Its 2.0 and 3.0 lines sit on the Draft 4 lineage, and 3.1 and later on 2020-12. Much of Draft 7’s traffic comes down to one library, the Python jsonschema library’s deprecated remote-$ref fetch path, which sends the User-Agent python-jsonschema (deprecated $ref resolution). It fetches a schema’s meta-schema over the network on every validation, doing exactly what the specification advises against: “implementations SHOULD NOT assume they should perform a network operation when they encounter a network-addressable URI”. That does not make Draft 7’s lead fake, though. The library only fetches the Draft 7 meta-schema because the schemas people feed it are Draft 7, so the usage is real. The deprecated path just tilts the analytics further in its favour.
The other surprise is at the modern end. 2020-12 has been out for nearly six years, and OpenAPI 3.1 adopted it back in February 2021. Yet it is still not the most-