Solving the JSON Schema dialect fragmentation problem with auto-upgrades

wpnews.pro

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). 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:

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` , redefined from decimal places to divisibility.
Draft 3	2010	`optional` replaced by`required` with inverted meaning.`maximumCanEqual` /`minimumCanEqual` replaced by`exclusiveMaximum` /`exclusiveMinimum` .`requires` renamed to`dependencies` .`format` dropped the address-oriented values`street-address` ,`locality` ,`region` ,`postal-code` and`country` .
Draft 4	2013	`required` changed from a per-property boolean flag to an array of names.`disallow` and`extends` removed.`divisibleBy` renamed to`multipleOf` .`type` dropped the`"any"` value and can no longer hold inline subschemas.`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` renamed to`$id` . Boolean`exclusiveMinimum` /`exclusiveMaximum` became numeric.`type"integer"` now accepts values like`1.0` .
Draft 7	2018	None. Backward-compatible with Draft 6.
2019-09	2019	`definitions` renamed to`$defs` . `dependencies` split into`dependentRequired` and`dependentSchemas` . Plain-name anchors moved from an`$id` fragment to`$anchor` , and`$ref` may now sit beside other keywords.
2020-12	2020	Array `items` and`additionalItems` became`prefixItems` and`items` .`$recursiveRef` /`$recursiveAnchor` replaced by`$dynamicRef` /`$dynamicAnchor` .`contains` now marks matched items as evaluated, changing`unevaluatedItems` results.`$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” , with non-standard spellings like`defaultValue` (not`default` ) and`minimum` /`maximum` given as strings.
Swagger / OpenAPI 2.0	2014	“a subset of JSON Schema Draft 4” with OpenAPI-only additions (`discriminator` ,`readOnly` ,`xml` ,`externalDocs` ,`example` ) and its own`format` values (`int32` ,`int64` ,`float` ,`double` ,`byte` ,`binary` ,`password` ).`type` must be single-valued, and only`allOf` is supported among the logical applicators.
OpenAPI 3.0.x	2017	“an extended subset of the JSON Schema Specification Wright Draft 00” (Draft 4 lineage), adding`nullable` ,`discriminator` ,`readOnly` ,`writeOnly` ,`xml` ,`externalDocs` ,`example` ,`deprecated` and its own`format` values (`int32` ,`int64` ,`byte` ,`binary` ,`password` ).`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” , defining anOpenAPI Schema Object dialect whose base vocabulary adds four keywords (`discriminator` ,`xml` ,`externalDocs` , and`example` ).
OpenAPI 3.2	2025	Also a superset of 2020-12 , with itsown base vocabulary carrying the same four keywords in revised form.`example` is now deprecated, and`xml` gains a`nodeType` while deprecating`attribute` and`wrapped` .

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.

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 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 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"`
JSON Schema	Draft 1	487	`"json-schema.org/draft-01/schema"`
JSON Schema	Draft 2	489	`"json-schema.org/draft-02/schema"`
JSON Schema	Draft 3	28,288	`"json-schema.org/draft-03/schema"`
JSON Schema	Draft 4	444,416	`"json-schema.org/draft-04/schema"`
JSON Schema	Draft 6	194,560	`"json-schema.org/draft-06/schema"`
JSON Schema	Draft 7	839,680	`"json-schema.org/draft-07/schema"`
JSON Schema	2019-09	63,744	`"json-schema.org/draft/2019-09/schema"`
JSON Schema	2020-12	829,440	`"json-schema.org/draft/2020-12/schema"`
OpenAPI	2.0 (Draft 4 lineage)	67,328	`"swagger: \"2.0\""`
OpenAPI	3.0 (Draft 4 subset)	307,200	`"openapi: 3.0"`
OpenAPI	3.1 (2020-12)	100,352	`"openapi: 3.1"`
OpenAPI	3.2 (2020-12)	1,824	`"openapi": "3.2.0"`
AsyncAPI	2.x + 3.0 (Draft 7)	13,088	`"asyncapi: 2"` ,`"asyncapi: 3"`

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.

The SchemaStore catalogue

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.

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 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 ‘<name>’ has an invalid outputSchema: JSON Schema declares an unsupported dialect ("$schema": “http://json-schema.org/draft-07/schema#"). The default validator supports JSON Schema 2020-12 only

That one report drew 54 comments (claude-code #86142), and the cause is mundane. The SDK “falls back to ‘draft-7’ whenever no explicit target is passed” (typescript-sdk #2721).

The same error shows up in other MCP projects too, like the reference file server (servers #4841) and the mcp-use client (mcp-use #1839). But this is not an MCP problem. It is what any single-dialect tool does. AJV 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). And some tools never made the jump at all, like react-jsonschema-form, which still cannot handle 2020-12 (rjsf #3750, rjsf #3751).

The same loud failure happens keyword by keyword, not only for a schema as a whole. 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). Array items became prefixItems in 2020-12, crashing generators that still expect an items key, with orval dying on All arrays must have an items key define (orval #890) and openapi-generator hitting the same wall twice (openapi-generator #19704, openapi-generator #17923). And keywords like minContains or $anchor are flagged “unknown” under the wrong dialect (AJV #1872, AJV #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.”

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’s published spec (svix #2551, fastify-swagger #954). Other changes are just as quiet. An exclusiveMinimum bound can vanish on upgrade, “left as undefined” with nothing flagged (scalar #10235). A bare type: "null" can conjure a phantom model in a code generator (openapi-generator #24520). In n8n, 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).

The mixed-dialect trap

JSON Schema was designed to let a single document mix dialects. 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 no longer exists. The CoverageJSON 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 is based on 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).

The same failure shows up wherever a cross-dialect reference is bundled or resolved. Redocly trips on bundling a 2020-12 root into an OpenAPI 3.1 spec (redocly-cli #1613), json-schema-ref-parser on the $id and $ref changes from 2019-09 (json-schema-ref-parser #145), python-jsonschema on an embedded 2020-12 meta-schema (python-jsonschema #884) and on a resolver rewrite that broke a working STAC schema (python-jsonschema #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 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	json-schema-migrate-x	jsonschema-migrate (Rust)	Sourcemeta
Repoints `$ref` after a keyword moves	No	No	Partial (only `#/definitions` )	Yes
Fixes `$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, swagger2openapi, and openapi-down-convert, are left out of the table above, since none can take a standalone JSON Schema.

JSON Schema is a complex language, 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 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 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 to $id, moved the per-property required flag up into an array, and turned divisibleBy into multipleOf. Each use of dependencies split by form, the schema-valued one into dependentSchemas and the property list into dependentRequired. The $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 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 into a document left in the old dialect. The full contract is in the Sourcemeta One HTTP API.

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 or 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, from a Google Summer of Code project, found that more cases are possible than expected.

Swagger 2.0. Auto-upgrade starts at OpenAPI 3.0, not the older Swagger 2.0. 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 after one 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.

source & further reading

sourcemeta.com — original article