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-requested dialect, and it has barely moved since a 2023 article that inspected the same Cloudflare analytics. Some of that gap is measurement, since the modern tools that use 2020-12 are the ones most likely to ship the meta-schemas as built-in copies and validate against those rather than fetch them over the network, so the figures understate it. But the persistence is also the point. That same python-jsonschema traffic was already there in 2023, which means whoever was validating those Draft 7 schemas then is still doing it now, and still has not upgraded.

A last quirk we cannot explain is that 2020-12’s core vocabulary meta-schema is requested nearly twice as often as the dialect meta-schema that references it.

What developers actually declare on GitHub tells a compatible story. Every dialect’s meta-schema lives at a distinct URL, and each version of OpenAPI and AsyncAPI leaves a distinct marker in its documents. So a text search for those strings is a rough headcount of what people publish.

The table below runs one such query per row against GitHub’s code search API on September 28th, 2026, and links each one so you can re-run it. This is text matching over the API, not schema parsing. It counts every file containing the string, including generated and vendored copies, which inflates the newest dialects most. GitHub also returns the totals as estimates. So treat the numbers as approximate, good enough as one more proxy, where the ranking matters more than any exact figure.

Draft 7 leads here too, now by published files rather than by requests. The one real divergence is 2020-12, which ranks higher by file count than by traffic. Even that reflects the measurement bias pulling each way. File counts are inflated by generated and vendored copies, while the traffic figures understate 2020-12 because modern tools ship the meta-schemas as built-in copies instead of fetching them.

Draft 4 is the other constant. It no longer leads by raw file count, but its lineage is what most public APIs still run on: OpenAPI 2.0 and 3.0 are both custom Draft 4 dialects, and together they still outnumber the 2020-12-aligned OpenAPI 3.1 by a wide margin, years after 2020-12 shipped. The extremes behave as expected, with the earliest drafts effectively extinct and OpenAPI 3.2, released only in September 2025, barely registering yet.

A study from 2020 shows how recent Draft 7’s rise really is. An Empirical Study on the “Usage of Not” in Real-World JSON Schema Documents crawled GitHub in July 2020, removed duplicate copies, and found that across 82,094 files Draft 4 was declared by 78.85% and Draft 7 by only 2.67%, with Draft 6 and Draft 3 in between. That makes sense for the time. 2020-12 was not out yet, and Draft 7 was only two years old. Draft 4 was still the clear default. Our own numbers, where Draft 7 now leads, show how far it has come since 2020.

One curated catalogue is worth a closer look. SchemaStore is a large public collection of JSON schemas for common configuration files. It is created and maintained by Mads Kristensen, a longtime Visual Studio program manager at Microsoft. It is also overwhelmingly Draft 7. Of the 977 standalone schemas we analysed on September 28th, 2026, 89.3% declare Draft 7, only 7.4% declare 2020-12, just 1.1% Draft 4, and 1.7% declare no dialect at all.

That is the mirror image of the OpenAPI-driven proxies, where Draft 4 and 2020-12 lead and Draft 7 barely featured. The difference is what SchemaStore is for. Visual Studio and Visual Studio Code draw on it for JSON and YAML auto-completion. It lives entirely in the configuration-and-editor world, which has no OpenAPI in it, so Draft 7 dominates. This suggests that much of Draft 7’s lead in the earlier proxies comes from this world rather than from APIs, and it is not a small one.

So far we have counted schemas. The following table instead takes real adopters of JSON Schema, commercial products, open-source projects, and standards whose published artefact is the schema itself, and groups them by the dialect each one uses. It is not exhaustive, and it reflects what each project’s own documentation or published schemas state at the time of writing. Adopters that support several dialects appear in every row they belong to, so the numbers are row entries, not unique adopters.

The pattern is that no single dialect wins. Real, current adopters span four eras at once, from Draft 3 to 2020-12, and every one of them is still a production dependency for someone. Draft 4 and Draft 7 carry the longest tails, especially on the commercial side, while 2019-09 was skipped almost entirely and 2020-12 is the one clearly gaining ground, mostly among newer AI and data products. The split is sharp even inside a single category: among API gateways alone, Kong, AWS API Gateway, Apache APISIX, Gravitee, and Axway validate against Draft 4, NGINX App Protect reaches Draft 7, Zuplo is on 2020-12, and KrakenD supports several at once, so even a task as narrow as validating requests in a gateway has no one-dialect answer. The LLM structured-output APIs are worse still, each accepting its own incompatible subset that is not a clean dialect at all.

The fragmentation is not a theoretical worry. It surfaces as a steady stream of GitHub issues, and the same failures show up from one project to the next, often with similar error strings. Here is what it looks like, one trap at a time.

A tool that supports exactly one dialect does not adapt to a schema written in another. It rejects it outright, before any validation happens, so the mismatch surfaces as a flat refusal rather than a wrong answer. The clearest live example is the Model Context Protocol, where servers built with the MCP TypeScript SDK tag their tool schemas as Draft 7 while Claude’s client validates against 2020-12 and