# Solving the JSON Schema dialect fragmentation problem with auto-upgrades
> Source:
> Published: 2026-10-30 20:49:12+00:00
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.
## JSON Schema evolves, and evolution brings breaking changes
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](https://openproceedings.org/2025/conf/edbt/paper-T3.pdf)). Today, it is
[the one schema language every major AI provider (OpenAI, Google, Anthropic,
Mistral, xAI, DeepSeek) has converged on](https://www.sourcemeta.com/blog/ai-only-speaks-json-schema/), and the format the Model Context
Protocol speaks. It is what [every G7 government runs its digital public
infrastructure on](https://www.sourcemeta.com/blog/g7-runs-on-json-schema/), and from
December 2026 every EU country must run its [eIDAS 2.0 digital
identity](https://github.com/EWC-consortium/eudi-wallet-rulebooks-and-schemas/tree/main/data-schemas)
system on it as well. Whatever you are building, you almost certainly depend
on JSON Schema, directly or [through OpenAPI](https://www.sourcemeta.com/blog/json-schema-dominates-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`](https://www.learnjsonschema.com/draft4/core/id/) was
renamed to [`$id`](https://www.learnjsonschema.com/draft6/core/id/). Others
are far more subtle, like how the
[`$anchor`](https://www.learnjsonschema.com/2020-12/core/anchor/) keyword
[accepted colons in
2019-09](https://www.learnjsonschema.com/2019-09/core/anchor/) but [no longer
does in 2020-12](https://www.learnjsonschema.com/2020-12/core/anchor/).
The result is a family of dialects, each with its own set of breaking changes:
| Dialect | Year | Breaking changes |
|---|---|---|
| Draft 0 | 2009 | The first published draft. |
| Draft 1 | 2009 | No schema changes (an IETF metadata revision). |
| Draft 2 | 2010 | `maxDecimal` replaced by[`divisibleBy`](https://www.learnjsonschema.com/draft3/core/divisibleby/) , redefined from decimal places to divisibility. |
| Draft 3 | 2010 | `optional` replaced by[`required`](https://www.learnjsonschema.com/draft3/core/required/) with inverted meaning.`maximumCanEqual` /`minimumCanEqual` replaced by[`exclusiveMaximum`](https://www.learnjsonschema.com/draft3/core/exclusivemaximum/) /[`exclusiveMinimum`](https://www.learnjsonschema.com/draft3/core/exclusiveminimum/) .`requires` renamed to[`dependencies`](https://www.learnjsonschema.com/draft3/core/dependencies/) .[`format`](https://www.learnjsonschema.com/draft3/core/format/) dropped the address-oriented values`street-address` ,`locality` ,`region` ,`postal-code` and`country` . |
| Draft 4 | 2013 | [`required`](https://www.learnjsonschema.com/draft4/validation/required/) changed from a per-property boolean flag to an array of names.[`disallow`](https://www.learnjsonschema.com/draft3/core/disallow/) and[`extends`](https://www.learnjsonschema.com/draft3/core/extends/) removed.[`divisibleBy`](https://www.learnjsonschema.com/draft3/core/divisibleby/) renamed to[`multipleOf`](https://www.learnjsonschema.com/draft4/validation/multipleof/) .[`type`](https://www.learnjsonschema.com/draft4/validation/type/) dropped the`"any"` value and can no longer hold inline subschemas.[`format`](https://www.learnjsonschema.com/draft4/validation/format/) was pruned to six values (`date` ,`time` ,`utc-millisec` ,`regex` ,`color` ,`style` and`phone` removed, with`ip-address` and`host-name` renamed to`ipv4` and`hostname` ). |
| Draft 5 | 2016 | No schema changes (a cleanup of Draft 4 that kept its meta-schemas). |
| Draft 6 | 2017 | [`id`](https://www.learnjsonschema.com/draft4/core/id/) renamed to[`$id`](https://www.learnjsonschema.com/draft6/core/id/) . Boolean[`exclusiveMinimum`](https://www.learnjsonschema.com/draft6/validation/exclusiveminimum/) /[`exclusiveMaximum`](https://www.learnjsonschema.com/draft6/validation/exclusivemaximum/) became numeric.[`type`](https://www.learnjsonschema.com/draft6/validation/type/)`"integer"` now accepts values like`1.0` . |
| Draft 7 | 2018 | None. Backward-compatible with Draft 6. |
| 2019-09 | 2019 | [`definitions`](https://www.learnjsonschema.com/draft7/validation/definitions/) renamed to[`$defs`](https://www.learnjsonschema.com/2019-09/core/defs/) .[` dependencies`](https://www.learnjsonschema.com/draft7/validation/dependencies/) split into[`dependentRequired`](https://www.learnjsonschema.com/2019-09/validation/dependentrequired/) and[`dependentSchemas`](https://www.learnjsonschema.com/2019-09/applicator/dependentschemas/) . Plain-name anchors moved from an[`$id`](https://www.learnjsonschema.com/2019-09/core/id/) fragment to[`$anchor`](https://www.learnjsonschema.com/2019-09/core/anchor/) , and[`$ref`](https://www.learnjsonschema.com/2019-09/core/ref/) may now sit beside other keywords. |
| 2020-12 | 2020 | Array [`items`](https://www.learnjsonschema.com/2019-09/applicator/items/) and[`additionalItems`](https://www.learnjsonschema.com/2019-09/applicator/additionalitems/) became[`prefixItems`](https://www.learnjsonschema.com/2020-12/applicator/prefixitems/) and[`items`](https://www.learnjsonschema.com/2020-12/applicator/items/) .[`$recursiveRef`](https://www.learnjsonschema.com/2019-09/core/recursiveref/) /[`$recursiveAnchor`](https://www.learnjsonschema.com/2019-09/core/recursiveanchor/) replaced by[`$dynamicRef`](https://www.learnjsonschema.com/2020-12/core/dynamicref/) /[`$dynamicAnchor`](https://www.learnjsonschema.com/2020-12/core/dynamicanchor/) .[`contains`](https://www.learnjsonschema.com/2020-12/applicator/contains/) now marks matched items as evaluated, changing[`unevaluatedItems`](https://www.learnjsonschema.com/2020-12/unevaluated/unevaluateditems/) results.[`$anchor`](https://www.learnjsonschema.com/2020-12/core/anchor/) dropped the colon from its allowed characters. |
## And those breaking changes cascade to JSON Schema’s adopters
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:
| Version | Year | JSON Schema dialect |
|---|---|---|
| Swagger 1.2 | 2014 | Reuses JSON Schema Draft 4’s primitive types ( `type` plus a`format` modifier), but its Models and Properties are Swagger’s own objects that each[*“follows a subset of the JSON-Schema specification”*](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/1.2.md) , with non-standard spellings like`defaultValue` (not[`default`](https://www.learnjsonschema.com/draft4/validation/default/) ) and`minimum` /`maximum` given as strings. |
| Swagger / OpenAPI 2.0 | 2014 | [*“a subset of JSON Schema Draft 4”*](https://spec.openapis.org/oas/v2.0.html) with OpenAPI-only additions (`discriminator` ,`readOnly` ,`xml` ,`externalDocs` ,`example` ) and its own`format` values (`int32` ,`int64` ,`float` ,`double` ,`byte` ,`binary` ,`password` ).[`type`](https://www.learnjsonschema.com/draft4/validation/type/) must be single-valued, and only[`allOf`](https://www.learnjsonschema.com/draft4/validation/allof/) is supported among the logical applicators. |
| OpenAPI 3.0.x | 2017 | [*“an extended subset of the JSON Schema Specification Wright Draft 00”*](https://spec.openapis.org/oas/v3.0.3.html) (Draft 4 lineage), adding`nullable` ,`discriminator` ,`readOnly` ,`writeOnly` ,`xml` ,`externalDocs` ,`example` ,`deprecated` and its own`format` values (`int32` ,`int64` ,`byte` ,`binary` ,`password` ).[`type`](https://www.learnjsonschema.com/draft4/validation/type/) must be a single string (no`null` , use`nullable` ), and any JSON Schema keyword it does not list is*“strictly unsupported”* . |
| OpenAPI 3.1 | 2021 | [*“a superset of the JSON Schema Specification Draft 2020-12”*](https://spec.openapis.org/oas/v3.1.0.html) , defining an[OpenAPI Schema Object dialect](https://spec.openapis.org/oas/3.1/dialect/base) whose base vocabulary adds four keywords ([`discriminator`](https://www.learnjsonschema.com/2020-12/openapi-3.1/discriminator/) ,[`xml`](https://www.learnjsonschema.com/2020-12/openapi-3.1/xml/) ,[`externalDocs`](https://www.learnjsonschema.com/2020-12/openapi-3.1/externaldocs/) , and[`example`](https://www.learnjsonschema.com/2020-12/openapi-3.1/example/) ). |
| OpenAPI 3.2 | 2025 | Also [a superset of 2020-12](https://spec.openapis.org/oas/v3.2.0.html) , with its[own base vocabulary](https://spec.openapis.org/oas/3.2/dialect/2025-09-17) carrying the same four keywords in revised form.[`example`](https://www.learnjsonschema.com/2020-12/openapi-3.2/example/) is now deprecated, and[`xml`](https://www.learnjsonschema.com/2020-12/openapi-3.2/xml/) gains a`nodeType` while deprecating`attribute` and`wrapped` . |
OpenAPI is not the only one. The [Model Context
Protocol](https://modelcontextprotocol.io), the fast-growing standard that
wires AI models to tools and [also builds on JSON Schema](https://www.sourcemeta.com/blog/ai-only-speaks-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](https://modelcontextprotocol.io/seps/1613-establish-json-schema-2020-12-as-default-dialect-f)
(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](https://www.khronos.org/gltf/), Khronos’s
3D asset format, went [from Draft 4 to
2020-12](https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/2.0/schema/glTF.schema.json)
in 2021. [Docker Compose](https://compose-spec.io/) moved [from 2019-09 to
2020-12](https://raw.githubusercontent.com/compose-spec/compose-spec/master/schema/compose-spec.json)
in 2026. [SPDX](https://spdx.dev/), the software bill-of-materials standard,
went [from Draft 7 to
2020-12](https://raw.githubusercontent.com/spdx/spdx-spec/develop/schemas/spdx-schema-3-0-1.json)
with its 3.0 line in 2024. And [STAC](https://stacspec.org/), the
SpatioTemporal Asset Catalog for geospatial data, moved [from Draft 6 to Draft
7](https://raw.githubusercontent.com/radiantearth/stac-spec/v0.9.0/catalog-spec/json-schema/catalog.json)
in 2020. Whole products migrate too: [Confluent Schema
Registry](https://docs.confluent.io/platform/current/schema-registry/index.html),
Kafka’s schema registry, [added
2020-12](https://docs.confluent.io/platform/current/schema-registry/fundamentals/serdes-develop/serdes-json.html)
in Platform 7.6.0 in 2024, and [OpenMetadata](https://open-metadata.org/), an
open-source metadata platform, moved its entire schema corpus from Draft 7 to
2020-12 in [a single 2026 pull
request](https://github.com/open-metadata/OpenMetadata/pull/33631) touching
1,324 files.
## How fragmented is it, really?
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.
### Live traffic to the official website
Start with live traffic. The [json-schema.org](https://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](https://json-schema.org/draft-07/schema) leads by a wide margin, [Draft
4](https://json-schema.org/draft-04/schema) is a close second, and
[2020-12](https://json-schema.org/draft/2020-12/schema) only comes third, with
[Draft 6](https://json-schema.org/draft-06/schema) and
[2019-09](https://json-schema.org/draft/2019-09/schema) 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`](https://github.com/python-jsonschema/jsonschema) library’s
*[deprecated](https://github.com/python-jsonschema/jsonschema/pull/1049)*
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”*](https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.3).
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](https://json-schema.org/blog/posts/website-analytics-snapshot-2023).
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](https://json-schema.org/draft/2020-12/meta/core) is requested
nearly twice as often as the [dialect
meta-schema](https://json-schema.org/draft/2020-12/schema) that references it.
### What developers publish on GitHub
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.
| Specification | Version | Files on GitHub | Searched for |
|---|---|---|---|
| JSON Schema | Draft 0 | 398 | [`"json-schema.org/draft-00/schema"`](https://github.com/search?q=%22json-schema.org%2Fdraft-00%2Fschema%22&type=code) |
| JSON Schema | Draft 1 | 487 | [`"json-schema.org/draft-01/schema"`](https://github.com/search?q=%22json-schema.org%2Fdraft-01%2Fschema%22&type=code) |
| JSON Schema | Draft 2 | 489 | [`"json-schema.org/draft-02/schema"`](https://github.com/search?q=%22json-schema.org%2Fdraft-02%2Fschema%22&type=code) |
| JSON Schema | Draft 3 | 28,288 | [`"json-schema.org/draft-03/schema"`](https://github.com/search?q=%22json-schema.org%2Fdraft-03%2Fschema%22&type=code) |
| JSON Schema | Draft 4 | 444,416 | [`"json-schema.org/draft-04/schema"`](https://github.com/search?q=%22json-schema.org%2Fdraft-04%2Fschema%22&type=code) |
| JSON Schema | Draft 6 | 194,560 | [`"json-schema.org/draft-06/schema"`](https://github.com/search?q=%22json-schema.org%2Fdraft-06%2Fschema%22&type=code) |
| JSON Schema | Draft 7 | 839,680 | [`"json-schema.org/draft-07/schema"`](https://github.com/search?q=%22json-schema.org%2Fdraft-07%2Fschema%22&type=code) |
| JSON Schema | 2019-09 | 63,744 | [`"json-schema.org/draft/2019-09/schema"`](https://github.com/search?q=%22json-schema.org%2Fdraft%2F2019-09%2Fschema%22&type=code) |
| JSON Schema | 2020-12 | 829,440 | [`"json-schema.org/draft/2020-12/schema"`](https://github.com/search?q=%22json-schema.org%2Fdraft%2F2020-12%2Fschema%22&type=code) |
| OpenAPI | 2.0 (Draft 4 lineage) | 67,328 | [`"swagger: \"2.0\""`](https://github.com/search?q=%22swagger%3A%20%5C%222.0%5C%22%22&type=code) |
| OpenAPI | 3.0 (Draft 4 subset) | 307,200 | [`"openapi: 3.0"`](https://github.com/search?q=%22openapi%3A%203.0%22&type=code) |
| OpenAPI | 3.1 (2020-12) | 100,352 | [`"openapi: 3.1"`](https://github.com/search?q=%22openapi%3A%203.1%22&type=code) |
| OpenAPI | 3.2 (2020-12) | 1,824 | [`"openapi": "3.2.0"`](https://github.com/search?q=%22openapi%22%3A%20%223.2.0%22&type=code) |
| AsyncAPI | 2.x + 3.0 (Draft 7) | 13,088 | [`"asyncapi: 2"`](https://github.com/search?q=%22asyncapi%3A%202%22&type=code) ,[`"asyncapi: 3"`](https://github.com/search?q=%22asyncapi%3A%203%22&type=code) |
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](https://arxiv.org/abs/2107.08677)* 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.
### The SchemaStore catalogue
One curated catalogue is worth a closer look.
[SchemaStore](https://github.com/SchemaStore/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](https://www.youtube.com/watch?v=-yYTxLZZk58). 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.
## What dialects do real products and specs actually use?
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.
## Where fragmentation bites
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.
### The hard reject
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](https://github.com/modelcontextprotocol/typescript-sdk) tag
their tool schemas as Draft 7 while Claude’s client validates against 2020-12
and nothing else.
The schema is discarded before a single request is made, with an error that names the exact problem:
Tool ‘’ has an invalid outputSchema: JSON Schema declares an
unsupported dialect ("$schema": “[http://json-schema.org/draft-07/schema#"](http://json-schema.org/draft-07/schema#%22)).
The default validator supports JSON Schema 2020-12 only
That one report drew 54 comments ([claude-code
#86142](https://github.com/anthropics/claude-code/issues/86142)), and the
cause is mundane. The SDK *“falls back to ‘draft-7’ whenever no explicit
target is passed”* ([typescript-sdk
#2721](https://github.com/modelcontextprotocol/typescript-sdk/issues/2721)).
The same error shows up in other MCP projects too, like the reference file
server ([servers
#4841](https://github.com/modelcontextprotocol/servers/issues/4841)) and the
[mcp-use](https://github.com/mcp-use/mcp-use) client ([mcp-use
#1839](https://github.com/mcp-use/mcp-use/issues/1839)). But this is not an
MCP problem. It is what any single-dialect tool does.
[AJV](https://ajv.js.org) defaults to Draft 7, so feed it a 2020-12 schema and
it fails with `no schema with key or ref` unless you pass `--spec=draft2020`
([ajv-cli #251](https://github.com/ajv-validator/ajv-cli/issues/251)). And
some tools never made the jump at all, like
[react-jsonschema-form](https://github.com/rjsf-team/react-jsonschema-form),
which still cannot handle 2020-12 ([rjsf
#3750](https://github.com/rjsf-team/react-jsonschema-form/issues/3750), [rjsf
#3751](https://github.com/rjsf-team/react-jsonschema-form/issues/3751)).
The same loud failure happens keyword by keyword, not only for a schema as a
whole.
[`exclusiveMinimum`](https://www.learnjsonschema.com/2020-12/validation/exclusiveminimum/)
flipped from a boolean flag to a numeric bound between Draft 4 and Draft 6, so
a validator built for one form errors on the other ([kogosoftwarellc
#776](https://github.com/kogosoftwarellc/open-api/issues/776)). Array
[`items`](https://www.learnjsonschema.com/draft4/validation/items/) became
[`prefixItems`](https://www.learnjsonschema.com/2020-12/applicator/prefixitems/)
in 2020-12, crashing generators that still expect an `items` key, with
[orval](https://github.com/orval-labs/orval) dying on `All arrays must have an items key define` ([orval
#890](https://github.com/orval-labs/orval/issues/890)) and
[openapi-generator](https://github.com/OpenAPITools/openapi-generator) hitting
the same wall twice ([openapi-generator
#19704](https://github.com/OpenAPITools/openapi-generator/issues/19704),
[openapi-generator
#17923](https://github.com/OpenAPITools/openapi-generator/issues/17923)). And
keywords like
[`minContains`](https://www.learnjsonschema.com/2020-12/validation/mincontains/)
or [`$anchor`](https://www.learnjsonschema.com/2020-12/core/anchor/) are
flagged “unknown” under the wrong dialect ([AJV
#1872](https://github.com/ajv-validator/ajv/issues/1872), [AJV
#1854](https://github.com/ajv-validator/ajv/issues/1854)).
### The silent trap
Worse than a loud rejection is no error at all. A dialect change can render a
once-valid keyword unknown, sometimes changing a schema’s meaning by accident.
As JSON Schema TSC member Ben Hutton puts it, an unknown keyword [“is just
going to be ignored. You won’t get an error. It makes no noise.
Silence.”](https://words.benhutton.me/2025-01-20-openai-chatgpt-and-structured-output-with-json-schema-pt1)
The move from OpenAPI 3.0 to 3.1 is full of these. `nullable` was a real
keyword in 3.0 but does not exist in 2020-12, so a 3.1 document that still
emits it simply loses that information:
nullable: true is emitted as-is. OpenAPI 3.1 uses JSON Schema 2020-12, where nullable no longer exists … Tools reading a 3.1 document ignore it, so the nullability is silently lost.
The same silent drop runs through all 579 `nullable` occurrences in
[Svix](https://www.svix.com)’s published spec ([svix
#2551](https://github.com/svix/svix-webhooks/issues/2551), [fastify-swagger
#954](https://github.com/fastify/fastify-swagger/issues/954)). Other changes
are just as quiet. An
[`exclusiveMinimum`](https://www.learnjsonschema.com/2020-12/validation/exclusiveminimum/)
bound can vanish on upgrade, *“left as `undefined`”* with nothing flagged
([scalar #10235](https://github.com/scalar/scalar/issues/10235)). A bare
`type: "null"` can conjure a phantom model in a code generator
([openapi-generator
#24520](https://github.com/OpenAPITools/openapi-generator/issues/24520)). In
[n8n](https://n8n.io), the same Draft 7 versus 2020-12 mismatch from the hard
reject above never surfaces. The MCP server’s tool schemas are discarded for
declaring the wrong dialect, and the only sign is *“zero tools appear in chat,
with no visible error”* ([n8n
#36361](https://github.com/n8n-io/n8n/issues/36361)).
### The mixed-dialect trap
[JSON Schema was designed to let a single document mix
dialects](https://json-schema.org/draft/2020-12/json-schema-core.html). So a
2020-12 document that references a Draft 7 GeoJSON schema is spec-valid. The
tools, though, often disagree. For example, reference a Draft 7 schema from a
2020-12 document, and a tool may apply the newer dialect across the reference,
where a keyword like
[`dependencies`](https://www.learnjsonschema.com/draft7/validation/dependencies/)
no longer exists. The [CoverageJSON](https://covjson.org) maintainers hit
exactly this wall:
OpenAPI 3.1 base their schema on JSON Schema Specification Draft 2020-12 …
But [https://covjson.org/schema/dev/coveragejson.json](https://covjson.org/schema/dev/coveragejson.json) is based on
[http://json-schema.org/draft-07/schema](http://json-schema.org/draft-07/schema), which is an older version of
JSON-Schema.
The thread ran to 24 comments before it was understood ([CoverageJSON
#205](https://github.com/opengeospatial/CoverageJSON/issues/205)).
The same failure shows up wherever a cross-dialect reference is bundled or
resolved. [Redocly](https://github.com/Redocly/redocly-cli) trips on bundling
a 2020-12 root into an OpenAPI 3.1 spec ([redocly-cli
#1613](https://github.com/Redocly/redocly-cli/issues/1613)),
[json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser)
on the [`$id`](https://www.learnjsonschema.com/2020-12/core/id/) and
[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref/) changes from
2019-09 ([json-schema-ref-parser
#145](https://github.com/APIDevTools/json-schema-ref-parser/issues/145)),
[python-jsonschema](https://github.com/python-jsonschema/jsonschema) on an
embedded 2020-12 meta-schema ([python-jsonschema
#884](https://github.com/python-jsonschema/jsonschema/issues/884)) and on a
resolver rewrite that broke a working STAC schema ([python-jsonschema
#1064](https://github.com/python-jsonschema/jsonschema/issues/1064)).
### Why multi-dialect tooling is not enough
So the obvious fix suggests itself: make every tool speak every dialect. Many already try, since general-purpose validators tend to support several dialects at once. But that alone cannot close the gap. Even a perfectly multi-dialect validator has no say over what happens next, as your schema flows on into someone else’s gateway, code generator, editor, and LLM endpoint. There will always be one more consumer, or one more publisher, working in a different dialect than you expected. Making every tool speak every dialect is the right idea in principle and impossible to guarantee in practice.
## Auto-upgrade the schema, and why nobody has finished the job
The holy grail is easy to state. You write a schema once, in whatever dialect was current at the time, and from then on your tooling transforms it on the fly into whatever dialect each consumer needs, including dialects that have not been published yet. The endless question of which dialect to write in, which dialect to support, which dialect a given tool happens to speak, simply disappears for good.
This is what Sourcemeta’s
[auto-upgrade](https://github.com/sourcemeta/jsonschema/blob/main/docs/upgrade.markdown)
does. The idea itself is not new, and people have written dialect upgraders
for years, but none of them gets the whole job right.
| Capability | [json-schema-migrate](https://github.com/ajv-validator/json-schema-migrate) | [json-schema-migrate-x](https://github.com/un-ts/json-schema-migrate-x) | [jsonschema-migrate](https://crates.io/crates/jsonschema-migrate) (Rust) | **[Sourcemeta](https://www.sourcemeta.com)** |
|---|---|---|---|---|
| Repoints [`$ref`](https://www.learnjsonschema.com/2020-12/core/ref/) after a keyword moves | No | No | Partial (only `#/definitions` ) | **Yes** |
| Fixes [`$anchor`](https://www.learnjsonschema.com/2020-12/core/anchor/) references | No (emits invalid names) | No (emits invalid names) | No (deletes anchors) | **Yes** |
| Guards new keywords | No | No | No | **Yes** |
| Embedded resources | Yes | Yes | No | **Yes** |
| Mixed-dialect documents | No (force one dialect) | No (force one dialect) | No (inner left unconverted) | **Yes** |
| Handles a stray `$schema` (invalid without`$id` ) | No (leaves it) | No (rewrites it to the 2020-12 URI) | No (leaves it) | **Yes** |
| Emits the requested dialect | No (writes 2019-09) | Yes | Yes | **Yes** |
| Source dialects | Draft 4 | Draft 4 | Draft 4 to 2019-09 | **Draft 3 to 2020-12, and OpenAPI 3.0/3.1** |
| Target dialects | Draft 6 to 2020-12 | Draft 6 to 2020-12 | 2020-12 only | **Draft 4 to 2020-12, and OpenAPI 3.1/3.2** |
| OpenAPI 3.0 schemas | No | No | No | **Yes** |
| OpenAPI 3.1 / 3.2 custom vocabularies | No | No | No | **Yes** |
| Maintained | No (2021) | Yes | Yes | **Yes** |
**Note:** tools that only upgrade schemas inside an OpenAPI document, such
as [Scalar’s
openapi-upgrader](https://www.npmjs.com/package/@scalar/openapi-upgrader),
[swagger2openapi](https://github.com/Mermade/oas-kit), and
[openapi-down-convert](https://github.com/apiture/openapi-down-convert), are
left out of the table above, since none can take a standalone JSON Schema.
JSON Schema is a [complex language](https://arxiv.org/abs/2307.10034), and
upgrading it correctly across dialects is a massive undertaking. The table
above is a non-exhaustive sample of the aspects that make it hard, and there
are many more, some extremely subtle, like the
[`$anchor`](https://www.learnjsonschema.com/2020-12/core/anchor/) keyword
quietly dropping the colon from its legal characters between 2019-09 and
2020-12. Sourcemeta is committed to getting all of them right, every time.
## Using it today
There are two ways to get a schema in the dialect a given tool expects, and they suit different workflows. The command line is for local development, where you upgrade a schema yourself when you need it. The registry is for publishing at an organisation’s scale, where you store one schema and let each consumer ask for the dialect it wants, so nobody upgrades anything by hand.
### The JSON Schema CLI
The [`jsonschema upgrade`](https://github.com/sourcemeta/jsonschema/blob/main/docs/upgrade.markdown)
command upgrades a schema on the spot. Point it at a file and name the target
dialect. Take this Draft 3 schema, which embeds a Draft 7 resource of its own:
```
{
"$schema": "http://json-schema.org/draft-03/schema#",
"id": "https://schemas.my-corp.com/order",
"type": "object",
"properties": {
"quantity": { "type": "integer", "divisibleBy": 5, "required": true },
"express": { "$ref": "#/dependencies/creditCard" },
"shipTo": {
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://schemas.my-corp.com/address",
"type": "object",
"dependencies": { "number": [ "street" ] }
}
},
"dependencies": {
"creditCard": { "required": [ "billingAddress" ] }
}
}
```
Run:
```
jsonschema upgrade order.json --to 2020-12
```
and you get:
```
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.my-corp.com/order",
"type": "object",
"required": [ "quantity" ],
"properties": {
"quantity": { "type": "integer", "multipleOf": 5 },
"express": { "$ref": "#/dependentSchemas/creditCard" },
"shipTo": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.my-corp.com/address",
"type": "object",
"dependentRequired": { "number": [ "street" ] }
}
},
"dependentSchemas": {
"creditCard": { "required": [ "billingAddress" ] }
}
}
```
In one pass it took the outer schema from Draft 3 to 2020-12. It renamed
[`id`](https://www.learnjsonschema.com/draft3/core/id/) to
[`$id`](https://www.learnjsonschema.com/2020-12/core/id/), moved the
per-property
[`required`](https://www.learnjsonschema.com/2020-12/validation/required/)
flag up into an array, and turned
[`divisibleBy`](https://www.learnjsonschema.com/draft3/core/divisibleby/) into
[`multipleOf`](https://www.learnjsonschema.com/2020-12/validation/multipleof/).
Each use of
[`dependencies`](https://www.learnjsonschema.com/draft3/core/dependencies/)
split by form, the schema-valued one into
[`dependentSchemas`](https://www.learnjsonschema.com/2020-12/applicator/dependentschemas/)
and the property list into
[`dependentRequired`](https://www.learnjsonschema.com/2020-12/validation/dependentrequired/).
The [`$ref`](https://www.learnjsonschema.com/2020-12/core/ref/) in `express`
repointed to match. The embedded `shipTo` resource is on a different dialect,
Draft 7. It was upgraded on its own terms in the same pass.
### Sourcemeta One
The command line is fine for a one-off, or a script that walks a directory. But an organisation can hold thousands of schemas across many dialects, owned by different teams and changing all the time. Upgrading each one by hand does not scale, and neither does keeping a converted copy for every consumer.
Say the `order` schema above lives in a [Sourcemeta
One](https://one.sourcemeta.com) instance at `schemas.my-corp.com`. You choose
the dialect you want with an `as` query parameter on the fetch URL. A team
still on an older validator asks for Draft 7:
```
https://schemas.my-corp.com/order?as=draft7
```
Another team on a modern stack asks the same path for 2020-12:
```
https://schemas.my-corp.com/order?as=2020-12
```
One schema is stored, and each consumer gets the dialect it asks for. Those URLs are ordinary references too, so they drop into whatever consumes the schema. An OpenAPI 3.1 description can point a request body straight at the 2020-12 form:
```
openapi: 3.1.0
info:
title: Orders
version: 1.0.0
paths:
/orders:
post:
requestBody:
content:
application/json:
schema:
$ref: "https://schemas.my-corp.com/order?as=2020-12"
```
A conversion always arrives bundled, so every reference inside travels already
converted. A consumer never follows a
[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref/) into a document
left in the old dialect. The full contract is in the [Sourcemeta One HTTP
API](https://one.sourcemeta.com/api/#fetch).
## Next steps
**Custom meta-schemas.** Auto-upgrade covers the official dialects, but not a
meta-schema or a schema that declares a custom one. A meta-schema describes a
dialect by naming that dialect’s keywords as ordinary data, often under
[`properties`](https://www.learnjsonschema.com/2020-12/applicator/properties/)
or
[`patternProperties`](https://www.learnjsonschema.com/2020-12/applicator/patternproperties/).
Upgrading renames the keywords in a schema, but it cannot tell which of those
data strings also meant a keyword and should move with them. So a conversion
can succeed and still leave the result out of step with the meta-schema, and
the meta-schema with its vocabularies. We are exploring meta-schema-level
hints to carry the intent that cannot be inferred today.
**Downgrades.** Auto-upgrade only goes one way today. Going the other way is
harder, since a newer dialect can often express things an older one cannot.
Our [preliminary
research](https://github.com/json-schema-org/upgrade-downgrade-rules), from a
[Google Summer of Code
project](https://github.com/json-schema-org/community/issues/599), found that
more cases are possible than expected.
**Swagger 2.0.** Auto-upgrade starts at OpenAPI 3.0, not the older [Swagger
2.0](https://spec.openapis.org/oas/v2.0.html). There has been almost no demand
for it, and the numbers above show it trailing OpenAPI 3.0 several times over.
We will consider adding it if enough people ask.
The specification is also trying to end new fragmentation at the source. Its
next release, JSON Schema v1, makes [backward compatibility a
priority](https://json-schema.org/blog/posts/stable-json-schema) after [one
last breaking change](https://json-schema.org/blog/posts/the-last-breaking-change).
But that is the long game, and the dialects already deployed are not going
anywhere, as the numbers above show. Auto-upgrade is for the fragmentation you
have now.