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 an OpenAPI 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 its own 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. json-schema.org meta-schema request paths over a trailing 30 days ending 2026-09-23 (Cloudflare analytics, site-owner data). Among dialect meta-schemas Draft 7 leads at 37.99M requests, Draft 4 is second at 25.3M, the 2020-12 dialect meta-schema is at 11.85M, Draft 6 at 7.84M, and 2019-09 at 1.38M. 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. The SchemaStore landing page and its public catalogue, 1,551 files at the time of writing. The project is run by volunteers and, by its own account, serves more than a terabyte a day. Source: schemastore.org 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. Dialect Count Commercial OSS Schemas / Standards Draft 3 3 Informatica B2B, Sourcemeta One Jackson jsonSchema module — Draft 4, and OpenAPI 2.0 and 3.0 37 AWS API Gateway, AWS EventBridge Schema Registry, Azure ARM templates, MongoDB $jsonSchema, Google Gemini / Vertex, Kong, Gravitee, Axway API Gateway, IBM App Connect, Cloudflare (OpenAPI 3.0), Heroku Platform API (Hyper-Schema), Microsoft json-schemas, Zapier, Adobe Experience Manager, Apiary, Assertible, SpreadJS, Lightblue, API7, Sourcemeta One, Confluent Schema Registry, AWS Glue Schema Registry Kubernetes CRDs, MySQL, Apache APISIX, Snowplow / Iglu, Nakadi, postgres-json-schema, NCI Genomic Data Commons, Mozilla Data Pipeline, Drupal Patternkit, OpenAPI 3.0.x, RAML 1.0, KrakenD, Apicurio Registry JSON-LD (document linter), UK Open Banking Standard (OpenAPI 3.0) Draft 6 9 API7, Sourcemeta One, Confluent Schema Registry, AWS Glue Schema Registry quicktype, Apache APISIX, KrakenD, Apicurio Registry FHIR Draft 7, the crowded middle 30 Decisions, DocSpring, NGINX App Protect, API7, Sourcemeta One, Confluent Schema Registry, AWS Glue Schema Registry Backstage, GitHub Actions / Dependabot (SchemaStore), Helm charts, WordPress theme.json, Ory Kratos, Renovate, dbt, zod-to-json-schema, typescript-json-schema, CloudEvents, AsyncAPI 2.x/3.0, Apache APISIX, KrakenD, Apicurio Registry FDC3, STAC, GeoJSON, CycloneDX, SPDX, NIST OSCAL, Human Cell Atlas, TILT, SDF (IETF ASDF) 2019-09 5 Sourcemeta One KrakenD Linux kernel Devicetree bindings (dt-schema), Manfred Awesomic CV, MovieLabs OMC 2020-12 28 Anthropic Claude, AWS Bedrock, Oracle 23ai, Zuplo, Sourcemeta One, Confluent Schema Registry, dottxt nf-core, TypeSpec, pydantic v2, invopop/jsonschema + schemars v1, OpenAPI 3.1, OpenTelemetry, Docker Compose, JSON:API, Arazzo, APIs.json, KrakenD, Apicurio Registry ISO 20022 (JSON), glTF (Khronos), Smart Data Models, NinJS (IPTC), RDA DMP Common, MCP, A2A, OSSF OSV, NASA GCN Unclear 14 LLM APIs, each a different bespoke subset: OpenAI, Azure OpenAI, Cohere, Groq, Mistral, Together AI. No dialect declared: Retool, JamF, Azure API Management, Walmart No dialect declared: Serverless, WSO2 API Manager OSS constrained decoding, bespoke subset: vLLM, XGrammar — 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 same table, stacked by what kind of adopter each entry is. Draft 4’s lead is mostly commercial, 22 of its 37 entries, while Draft 7 and 2020-12 lean open source and standards. An adopter that supports several dialects is counted in each one, so the bars are row entries rather than unique adopters. Source: each project’s own documentation or published schemas 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.
TL;DR: The same JSON Schema that validates your data can now declare what that data means. We built a ten-keyword extension vocabulary (x-jsonld-*) that promotes instances to JSON-LD (the JSON serialisation of RDF). Annotate the schemas you already have, and every payload they validate becomes knowledge-graph-ready. Over the past decade, everyone from MuleSoft to Adobe to the Italian government attempted some version of this bridge, and every attempt fell short of the same hard part: composition. We solved it, and it ships today in the JSON Schema CLI and in the Sourcemeta One registry. There is a fair chance JSON-LD lives in your head as “the schema.org blob you paste into a web page so Google shows rich results”. But JSON-LD is much more than that. It is one of the credential formats the EU Digital Identity Wallet accepts, which all 27 member states must ship by December 2026. It is the foundation of Microsoft’s Digital Twins Definition Language. It is how hundreds of thousands of machine-learning datasets describe themselves on Hugging Face and Kaggle, how all of EU law is published, and how websites talk to AI agents. JSON-LD is what JSON looks like when it graduates into a knowledge graph. And yet, from where the JSON Schema world sits, JSON-LD might as well be on another planet. It does not matter which door brought you to JSON Schema: OpenAPI specifications (76% of the modern ones are majority JSON Schema by volume), AsyncAPI message payloads, MCP tool definitions, W3C Web of Things Thing Descriptions, the IETF’s Semantic Definition Format for the Internet of Things, or plain standalone data models of the kind governments now publish in national registries. Sooner or later the same need appears: joining JSON Schema’s validation strengths with JSON-LD’s semantic strengths. The rest of this article covers how the two languages each won their own layer of the data world, who tried to bridge them over the past decade, where every attempt fell short, and how we made it work. Our JSON-LD extension vocabulary We built the bridge as a JSON Schema extension vocabulary: ten annotation keywords under the x-jsonld- prefix, deliberately continuing the convention introduced by the Italian government’s REST API Linked Data Keywords IETF draft. Because the keywords are plain x- extensions rather than a formal JSON Schema vocabulary, annotated schemas remain valid for every implementation, including the many with no vocabulary support at all. Here is a schema that describes a schema.org/Order whose seller and customer reuse a single party definition through $ref, where a party reuses a shared address, and where a party is a schema.org/Person or a schema.org/Organization depending on its kind. { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "x-jsonld-type": "https://schema.org/Order", "properties": { "orderNumber": { "type": "string", "x-jsonld-id": "https://schema.org/orderNumber" }, "seller": { "$ref": "#/$defs/party", "x-jsonld-id": "https://schema.org/seller" }, "customer": { "$ref": "#/$defs/party", "x-jsonld-id": "https://schema.org/customer" } }, "required": [ "orderNumber", "seller", "customer" ], "$defs": { "party": { "type": "object", "properties": { "kind": { "enum": [ "person", "organization" ] }, "name": { "type": "string", "x-jsonld-id": "https://schema.org/name" }, "address": { "$ref": "#/$defs/address", "x-jsonld-id": "https://schema.org/address" } }, "required": [ "kind", "name" ], "if": { "properties": { "kind": { "const": "person" } } }, "then": { "x-jsonld-type": "https://schema.org/Person" }, "else": { "x-jsonld-type": "https://schema.org/Organization" } }, "address": { "type": "object", "x-jsonld-type": "https://schema.org/PostalAddress", "properties": { "country": { "type": "string", "x-jsonld-id": "https://schema.org/addressCountry", "x-jsonld-self": "http://publications.europa.eu/resource/authority/country/{this}" } } } } } And here is an order payload, one company selling to one individual, the kind that would flow through a commerce API: { "orderNumber": "AC-2026-0042", "seller": { "kind": "organization", "name": "ACME GmbH", "address": { "country": "DEU" } }, "customer": { "kind": "person", "name": "Erika Mustermann", "address": { "country": "ITA" } } } Now let’s run this through the Sourcemeta JSON Schema CLI: $ jsonschema rdf schema.json instance.json Both parties come out of the same $ref with different RDF types, the seller an Organization and the customer a Person, each carrying an address typed as a schema.org/PostalAddress with its country promoted to the EU country authority IRI: [ { "@type": [ "https://schema.org/Order" ], "https://schema.org/orderNumber": [ { "@value": "AC-2026-0042" } ], "https://schema.org/seller": [ { "@type": [ "https://schema.org/Organization" ], "https://schema.org/name": [ { "@value": "ACME GmbH" } ], "https://schema.org/address": [ { "@type": [ "https://schema.org/PostalAddress" ], "https://schema.org/addressCountry": [ { "@id": "http://publications.europa.eu/resource/authority/country/DEU" } ] } ] } ], "https://schema.org/customer": [ { "@type": [ "https://schema.org/Person" ], "https://schema.org/name": [ { "@value": "Erika Mustermann" } ], "https://schema.org/address": [ { "@type": [ "https://schema.org/PostalAddress" ], "https://schema.org/addressCountry": [ { "@id": "http://publications.europa.eu/resource/authority/country/ITA" } ] } ] } ] } ] The seller and customer were typed differently from the same definition, and the address mapping, written once, applied to both, because the annotations compose through $ref exactly as validation does. One schema. One pass. If the instance is invalid, no RDF comes out at all. That output is in standard JSON-LD expanded form, canonical and context-free. If you would rather keep the document looking like the JSON your consumers already parse, compact it against a context of your choosing. For example, consider this context.json: { "@context": { "schema": "https://schema.org/", "orderNumber": "schema:orderNumber", "seller": "schema:seller", "customer": "schema:customer", "name": "schema:name", "address": "schema:address", "country": { "@id": "schema:addressCountry", "@type": "@id", "@context": { "@base": "http://publications.europa.eu/resource/authority/country/" } } } } You can convert to JSON-LD emitting the shape your consumers already know how to parse, with its semantics embedded, as follows: $ jsonschema rdf schema.json instance.json --compact context.json { "@type": "schema:Order", "orderNumber": "AC-2026-0042", "seller": { "@type": "schema:Organization", "name": "ACME GmbH", "address": { "@type": "schema:PostalAddress", "country": "DEU" } }, "customer": { "@type": "schema:Person", "name": "Erika Mustermann", "address": { "@type": "schema:PostalAddress", "country": "ITA" } }, "@context": { "schema": "https://schema.org/", "orderNumber": "schema:orderNumber", "seller": "schema:seller", "customer": "schema:customer", "name": "schema:name", "address": "schema:address", "country": { "@id": "schema:addressCountry", "@type": "@id", "@context": { "@base": "http://publications.europa.eu/resource/authority/country/" } } } } In other words, the context is your choice of projection. The schema annotations remain the single source of truth. JSON-LD and the knowledge graph economy Look again at what came out of that command. The expanded form is JSON-LD, which is the JSON serialisation of RDF, the W3C’s model for describing anything as a graph of subject-predicate-object (triple) statements. Build enough of those statements and you have a knowledge graph. The idea is simple: give every thing (such as a person, a country, a product, etc) one shared identifier, and record every fact as a link between those identifiers. Do that, and data scattered across systems, formats, and organisations becomes a single connected web that anyone, and any machine (including AI), can query across sources and reason over as a whole. That is the door our example quietly opened, and it leads somewhere very large. Almost everything you would call authoritative knowledge is already living in this way. Wikidata holds 1.65 billion statements. UniProt, the reference database of protein knowledge, exposes over 190 billion triples through what is widely cited as the largest public SPARQL endpoint on earth, and the US National Institutes of Health publishes its PubChem chemistry database as more than 130 billion triples of its own. Both are nodes in a life-sciences web that interlinks through the Linked Open Data cloud and its 1,658 connected datasets. Governments are wired the same way: every EU legal act is RDF behind a public endpoint, and France’s statistics office, its national library, and Europeana’s 50 million cultural objects all publish in it. Healthcare does the same through HL7 FHIR, which defines an RDF form for the records it moves between systems. So does big tech: Google, Microsoft, Facebook, eBay, and IBM each run their own. And it is how AI now gets its facts, since a model on its own is a parametric memory that hallucinates and the fix is to ground it in a graph, the pattern behind GraphRAG. France’s national library publishes its entire catalogue as linked data. Every record, like this one for Victor Hugo, the 19th-century French novelist behind Les Misérables, is a node in a knowledge graph, downloadable as RDF and JSON-LD (highlighted). Source: Bibliothèque nationale de France. None of them do this for tidiness. They do it because the graph is where data turns into value. We know that data is a valuable asset, but raw data is worth only what you can refine it into, and the knowledge graph is the refinery. When Google launched its Knowledge Graph in 2012 under the slogan “things, not strings”, search stopped matching text and started understanding entities. By 2016, Google reported that it held 70 billion facts and answered roughly a third of its 100 billion monthly searches straight from it. The mechanism is RDF’s shared identifiers. They allow independently produced data to become joinable, so the graph is worth more than the databases poured into it, and every entity added compounds the value of the ones already there. And this compounding now has a price. A data.world benchmark measured a language model at 16% accuracy over a raw SQL database and 54% over the same data as a knowledge graph. Gartner finds the organisations with the most mature data foundations achieve up to 65% greater business outcomes. And the knowledge graph market is projected to grow from $1.06 billion in 2024 to $6.93 billion by 2030. Bridging JSON Schema and JSON-LD Zooming out, structure and meaning are things you constantly need at once, and today they live in different languages. JSON Schema owns structure, whether the container is an OpenAPI specification, an AI tool definition, or a national data registry. Then, JSON-LD owns meaning, as the last section showed. The catch is that a single JSON document routinely needs both at once, and inside that document the two languages cannot see each other. A JSON Schema cannot say that family_name means schema.org/familyName, and a JSON-LD context cannot say that family_name is a required string conditional on the presence of first_name. A real Thing Description from the W3C Web of Things standard (Example 2). Most of it is JSON Schema (properties, type), sprinkled with JSON-LD to add meaning (@context, and @type: saref:LightSwitch pointing at a semantic vocabulary). The two languages sit in one document but do not integrate: the schema keywords cannot see the semantic ones, or the other way round. Source: W3C WoT Thing Description 1.1, Example 2. Now picture closing that gap. For example, the EU wallet schema already validates every credential a wallet API handles. Put the meaning inside it, and that one file also emits the knowledge graph. No second artefact to author, review, version, or keep in sync. The meaning is defined exactly once next to its validation constraints, and every payload pours into the graph for free. In other words, intermixing JSON Schema and JSON-LD gives the RDF world a powerful validation story, and it gives the JSON Schema world a significant upgrade in semantics and knowledge graph integration. The reason to state the prize so plainly is that the alternative, two artefacts kept in sync by hand, is everywhere, and it is a heavy tax. The Common Workflow Language project named it in 2015, when it abandoned existing schema languages because “none understand linked data”: “one must maintain separate JSON schema, JSON-LD context, RDF schema, and human documentation, despite significant overlap of content and obvious need for these documents to stay synchronized.” A decade later that tax is institutional: W3C Verifiable Credentials 2.0: the standard beneath the EU wallet, carries a JSON-LD @context for meaning and a separate credentialSchema for structure in every single credential. It takes a whole appendix to hold the two apart, a credentialSchema defining “the contents and structure of a set of claims” while a @context is “best used only for conveying the semantics and term definitions of the data”, and it takes the two “used in combination” before “both producers and consumers can be more confident about the expected contents and data types”. Nothing links them, so the companion specification can only advise the author: “It is advised to associate all properties that have a semantic mapping with a property in a credential schema.” That advice is the entire binding, and implementations show what it is worth. Credo, the OpenWallet Foundation’s wallet framework, ships the whole JSON-LD stack down to RDF canonicalisation and nineteen hand-authored context documents, while credentialSchema is modelled as an id and a type that it never fetches or evaluates. WE BUILD: one of the EU-co-funded Large Scale Pilots now building that wallet, keeps its credential JSON Schemas in one repository owned by one working group, while a second group hand-maintains the SKOS terminology, OWL vocabulary, and JSON-LD context in another. Nothing in the schemas points at the vocabulary, so the mapping between them survives in a third artefact: a Markdown table in the human-readable rulebook, under a column headed “Semantic Reference”, recording that family_name means w3id.org/ebwv#familyName while the schema next door can only call it a string. GS1’s EPCIS: the global supply-chain standard, ships EPCIS-JSON-Schema.json and epcis-context.jsonld side by side in one repository. FIWARE’s Smart Data Models: keep a schema for every entry in the catalogue, paired with a JSON-LD context. Gaia-X: Europe’s flagship cloud-federation project, pairs a JSON-LD self-description with a separate SHACL shape for every participant. Beckn: the open-commerce protocol from the architects of India’s Aadhaar and UPI, and the backbone of India’s government-backed ONDC network and its 200 million transactions, goes further still: it normatively requires every one of the 300+ concepts in its schema repository to ship four artefacts side by side, an OpenAPI envelope, a JSON Schema, a JSON-LD context, and an RDF vocabulary. Adobe: specified its Experience Data Model in both grammars at once, then had to bolt on a “Compatibility Mode” that flattens the JSON-LD namespacing out for its own platform. And the request to fix this at the source has sat open on the JSON Schema issue tracker since April 2017. Everyone pays the tax. Nobody has figured out how to fully remove it. The double edge of expressiveness So now you might wonder, with the prize this clear and the demand this old, why has this stayed unsolved? Because the obvious fix, embed the @context in the schema, only works on the easy case. That is what the Italian government’s REST API Linked Data Keywords IETF draft does. This is often enough for standalone simple schemas. But in practice, schemas are very often not standalone, and very often not simple. At scale, models of rich cross-referenced schemas are extremely common for schema reusability and data governance purposes. What makes it hard to solve this for complex schemas is the very thing JSON Schema is best at. JSON Schema is a remarkably expressive language. The meaning of a property can be split across files with $ref, combined through logical applicators like anyOf, or made to depend on the data in complex ways through if/then/else, and other similar keywords. With $dynamicRef a schema even resolves a reference differently depending on the context it is evaluated in, so there is no static document to analyse ahead of time and the meaning is decided during evaluation, against the data. This is why validating Modern JSON Schema is PSPACE-complete. In comparison, a JSON-LD context has none of this. It is a flat table of names, and it cannot follow a schema whose properties change meaning by position or by data. It could never, for instance, produce the order from our example, where the very same party definition became a Person or an Organization depending on a property in the payload. If you take this as a criticism, that JSON Schema is simply too complicated, you have it backwards. The complexity is not over-engineering. It is the language earning its keep. Most people who resent JSON Schema for its constraint-driven complexity have simply not yet met the problems that demand such complexity. And when they do, they are thankful that the expressiveness exists. A decade of attempts But all of that expressiveness is what a bridge to JSON-LD has to carry across, and it is why no one had built one that holds. Everyone who tried faced the same fork: strip the expressiveness away so the mapping to RDF turns easy, or keep it and try to pay the price. A decade of attempts went both ways, and came up short in both cases. The strippers made the problem vanish by not having it. The Common Workflow Language’s Schema Salad rebuilt the schema language on top of Avro, while LinkML and the automotive industry’s Catena-X generate JSON Schema from a separate RDF model you must author first. This path has real public-sector uptake: Switzerland’s eCH e-government standards group authors the data standards for the Swiss political system in LinkML precisely so that JSON Schema and OWL can be regenerated side by side on every commit, further proof of how badly the two worlds need each other. A simpler language projects into RDF more cleanly, but simplicity is the price: you surrender the conditionals and constraints that are the reason to reach for JSON Schema at all, and that no other mainstream schema language matches. “Those languages define structure”, as Charlie Holland puts it, while “JSON Schema defines structure and constraints”. The embracers kept JSON Schema and hit the wall head-on. The Open Geospatial Consortium’s tooling assembles the context from the schema at build time, and its own source carries a thirty-line comment about “binding bubbling”, where a referenced schema’s mappings silently overwrite the parent’s. India’s Beckn walks the same path today: its generator scripts scrape property names out of a schema and map each one to a flat beckn: IRI, blind to $ref (in one typical concept, four of the five terms in the published context sit behind references the generator cannot see), which is why the repository also carries scripts named schema_parity_audit.py and identify-and-fix-missing-context-vocab.py to patch the artefacts back into agreement. The credential world built the same thing and stopped in the same place: schemasToContext, from Transmute, which holds an editor’s seat on the VC JSON Schema specification, reads $linkedData annotations off a schema’s properties and flattens them into a context, and that design is the ecosystem’s convention: Hedera’s Guardian vendors the file itself, and the W3C CCG traceability vocabulary builds its context from its own copy of the same design. Each reads a single level of properties and resolves no $ref, leaving the caller to hand over every subschema up front, and Transmute’s source marks where it stops with a commented-out stub: // Need to handle anyOf and oneOf better.... Others went sideways: MuleSoft validated existing JSON-LD with JSON Schema before being archived at “pre-alpha”, and RML and the AI-assisted MetaConfigurator add a third artefact to drift from the other two. Even Adobe and Autodesk took runs at this JSON Schema and JSON-LD interoperability problem. How OGC’s tooling builds the JSON-LD context: a static second pass walks the compiled schema tree through every $ref, allOf, anyOf, and oneOf, collecting mappings into one flat @context. In their own words, “the assembly is really schema traversal”. It is re-creating evaluation at build time, and that is why it cannot follow a schema whose meaning depends on the data: with no instance to run against, a static walk has no way to know which if/then/else branch or $dynamicRef target applies. Source: OGC Building Blocks, semantic uplift documentation. Five ways to fall short For all their differences, the attempts share the same gaps. None couples validation and emission in one pass. None reproduces the composition inside the schema itself, and the closest do it as a lossy build step. None handles conditional meaning, and none mints identifiers from the data. The most serious attempt is telling in where it came from. Italy runs both worlds at national scale: a network of RDF ontologies that models its public administration as a knowledge graph, and a national platform of services described in OpenAPI and JSON Schema. It felt the collision before anyone else and set out to close it. Italy’s Core Person Vocabulary, one of the government RDF ontologies in its national semantic catalogue. It defines the concept of a Person, the same concept our example mapped, and is authored by the national statistics office (ISTAT) and digital agency (AgID). Running a whole network of these alongside a national JSON Schema API platform is why Italy hit the collision first. Source: schema.gov.it, Catalogo Nazionale della Semantica dei Dati. Even so, Roberto Polli’s REST API Linked Data Keywords IETF proposal for this problem (now at its ninth revision) admits the limit: “Automatic composability is not an explicit goal of this specification because of its complexity. […] These issues can be tackled in future versions of this specifications.” Against what a working solution actually needs, the pattern is stark: Attempt Standard JSON Schema Single evaluation pass Composition Conditional meaning IRI minting Polli draft (embed context) yes no no no no OGC (generate context) yes no partial no no Transmute, W3C CCG traceability (generate context) yes no no no no Schema Salad (new language) no no no no partial LinkML / Catena-X, automotive (separate model) no no no no no MuleSoft, Salesforce (validate JSON-LD) partial no $ref only no no RML / MetaConfigurator (mapping) no no no no yes Adobe XDM (maintain both by hand) partial no no no no Beckn / ONDC, India’s DPI (four parallel artefacts) yes no no no no Sourcemeta yes yes yes yes yes After a decade of attempts, from academic prototypes to Adobe, Salesforce, and the automotive industry, the wall was still standing. That is where we come in. How we cracked it So how do you carry all of that expressiveness into RDF? Every prior attempt treated the schema as a document to be parsed and mapped. We treat it as a program to be run. Sourcemeta maintains Blaze, a high-performance C++ JSON Schema validator that compiles a schema into a low-level program and executes it against an instance. Around that execution we built a full custom JSON-LD engine that rides along, producing the RDF in lockstep with the validation itself. So the meaning is built during evaluation, as part of the process, and the dynamism that defeated every static approach is carried by the run instead of fought. The result is full support for every construct JSON Schema has, in one file and one pass, with no second artefact to drift. The order from our initial example, which no prior tool could produce due to its use of some advanced keywords, is not a special case. It is simply what the engine does. If a schema can validate your data, it can now describe what that data means. Use it today The vocabulary is ten keywords under the x-jsonld- prefix, and the CLI documentation is for now the full reference (we are aiming for a proper spec around it soon). You can use it today from the command line by pointing jsonschema rdf at a schema and an instance, and get JSON-LD back, exactly as we did above. The ten x-jsonld-* keywords of the vocabulary, from the JSON Schema CLI documentation. Each annotates a subschema to map it into JSON-LD: x-jsonld-id for the predicate IRI a property maps to, x-jsonld-type for the node @type, x-jsonld-self to mint a node @id from instance values, and so on. Because they are plain x- extension keywords, annotated schemas stay valid for every other JSON Schema tool. Source: JSON Schema CLI RDF documentation But the command line is the small version of the idea. The same engine ships in Sourcemeta One, our flagship schema registry, where it runs over HTTP. Every schema the registry governs can turn an instance into JSON-LD on request, making meaning an API call (available through MCP too). With this, you can send your data to the registry and know what that data means, resolved against the schemas your organisation has already agreed on, so the transformation happens once, at the infrastructure layer, instead of being rebuilt inside every service. The idea is for schemas, their governance, and now their meaning to finally live in one place. So if you have data and you want to know what it means, you ask Sourcemeta One.
TL;DR: Every G7 government (United States, United Kingdom, France, Germany, Italy, Japan, and Canada) runs its digital public infrastructure on JSON Schema. So do nine out of ten of the OECD’s top digital governments in the 2025 ranking. France and Italy already operate national registries that support JSON Schema, and the Netherlands is building one. From December 2026, every EU country will run mandatory digital identity infrastructure on JSON Schema, under eIDAS 2.0. The public sector runs on APIs In 2015, TechCrunch declared that APIs fuel the software that’s eating the world. And as you probably know, the public sector is no exception. For example, the UK’s API Catalogue currently federates 1,791 API entries across UK public-sector publishers. The Netherlands’ national API registry currently lists 302 APIs. The community-run bund.dev portal currently indexes more than 60 German federal APIs. Italy publishes its API catalogue, which currently carries 14,672 e-services across 9,398 adhering public and private entities. Top PDND e-services by number of enabled entities, filtered to central public administrations as providers. PagoPA’s SEND digital-notifications service leads with around 7,000 enabled entities, followed by four ANNCSU address-registry services from Agenzia delle Entrate (around 5,032, 3,070, 2,509, and lower), then Ministero dell’Interno’s residence, family, and citizenship verification services, and AgID’s INAD digital-domicile registry. Source: PDND interop dashboard In terms of scale, Denmark’s Central Data Distribution Platform API “processes more than 70 million calls daily, and handles a daily data volume of 2.5 terabytes”. The United States data API is “used by 25 agencies for over 450 APIs”. South Korea’s data API offers “87,000 public data sets and 11,000 open APIs”. The UK Government Digital Service publishes an API exposing more than 8.4 million UK legal documents. Beyond datasets, the GOV.UK Notify API sent 12 billion messages by February 2026 on behalf of more than 11,000 public-sector services. Estonia’s X-Road API exchange links “more than 1,000 inter-connected databases covering some 1,700 services” and answers “more than 50 million enquiries every month”. In the US, the Law Enforcement Information eXchange (LInX) connects “thousands of law enforcement agencies” sharing “1.8 billion records amongst each other”. The AI wave is only reinforcing the fact that the public sector runs on APIs. As Kin Lane puts it, “MCP is an API”, and adoption within the public sector has already started. For example, consider the US GovInfo MCP, the US Census Bureau MCP, France’s data.gouv.fr MCP, Japan’s Digital Agency jgrants-mcp-server, and the UK Government Digital Service’s Parliament MCP. OpenAPI becomes national policy Like the rest of the industry, the public sector has also settled on OpenAPI as the format for describing APIs in a machine-human readable way. Many governments have explicitly written “use OpenAPI” into national API standards documents. For example, Canada mandates OpenAPI for all federal RESTful APIs. The United Kingdom’s Open Standards Board states that “Describing RESTful APIs with OpenAPI 3 is recommended by the government Open Standards Board”. Italy goes a step further: every API published on the National Digital Data Platform (PDND) is validated by “running the OAS Checker with the Italian Guidelines Full profile and obtaining 0 errors”. Japan’s Digital Agency states that “Government agencies are expected to adopt OAS […] to make development more efficient”. The following table offers a more exhaustive summary: Country Mandate or standard Source 🇨🇦 Canada Federal RESTful API mandate Standards on APIs 🇬🇧 United Kingdom Open Standards Board recommendation, GDS API technical and data standards guidance gov.uk 🇫🇷 France OAS required for national API registry submissions SEMIC 2024 🇮🇹 Italy Zero-error PDND validation gate (AgID) api-oas-checker-rules 🇯🇵 Japan Digital Agency DS-464-2 (Sept 2024) DS-464-2 🇦🇺 Australia NAPIDS MUST api.gov.au, source repo, architecture standard 🇳🇿 New Zealand Digital.govt.nz RECOMMEND, Te Whatu Ora HISO 10108 MUST, Draft NZ API Standard v1.0 (Nov 2025) API Guidelines, HISO 10108 🇫🇮 Finland OpenAPI 3 required at Suomi.fi DEL Suomi.fi DEL 🇪🇪 Estonia RIHA describes machine interfaces in OpenAPI RIHA-Index, Tehnoloogiavalikud 🇸🇬 Singapore APEX Cloud + GovTech OpenAPI Linter as a service, GovTech recommends modern standards such as OpenAPI apex.gov.sg 🇪🇸 Spain 2025 Practical Guide for publishing Open Data with APIs datos.gob.es 🇨🇭 Switzerland Federal guidelines MUST swiss/api-guidelines 🇧🇪 Belgium Belgif Federal Interoperability Framework, OpenAPI 3.0 Belgif 🇳🇱 Netherlands API Design Rules on Forum Standaardisatie’s comply-or-explain mandatory list since 2019 logius-standaarden Even beyond mandates, the European Commission found that “OAS was used by almost half of all reviewed API portals” across the European public-sector portals it surveyed. The picture extends across borders too. X-Road, an open-source data-exchange platform that uses OpenAPI to describe its REST services, was jointly founded by Estonia, Finland, and Iceland through the Nordic Institute for Interoperability Solutions (NIIS). Estonia operates it domestically as X-tee and Finland as the Suomi.fi data exchange layer. X-Road has been adopted as the national data exchange in Cambodia (as CamDX), Japan (via PlanetCross at Nichigas), El Salvador, and Kyrgyzstan (as Tunduk). Both OpenAPI and MCP are all about JSON Schema We have established that public-sector API adoption runs through OpenAPI and MCP. What is easy to miss, but more consequential, is that both share the same substrate: JSON Schema. More precisely, OpenAPI builds on top of JSON Schema. While OpenAPI offers syntax to declare endpoints and top-level metadata, what you use to actually describe request bodies, responses, headers, and query parameters is JSON Schema embedded within OpenAPI. In fact, we previously found that “in 76% of modern OpenAPI specs, JSON Schema dominates the specification”. So when governments work on OpenAPI at the scale we have just seen, they are, in the large majority, working on JSON Schema. A government OpenAPI mandate is, on closer reading, a JSON Schema mandate. From our study of public OpenAPI specifications across industry, the JSON Schema content embedded within an OpenAPI document often dominates the file. For well-known production APIs such as Mailchimp, the embedded JSON Schema can exceed 90% of the contents of the file. From In 76% of modern OpenAPI specs, JSON Schema dominates the specification The same principle holds for MCP. The official specification is built on JSON Schema 2020-12, and every MCP tool exposes its inputs as a JSON Schema object. The pattern reaches well beyond MCP. As we previously argued, “the only schema language AI speaks is JSON Schema”. Every major LLM provider’s tool-calling interface, every AI product, and every agent framework has converged on the same substrate. As Charlie Holland puts it, JSON Schema has become “the interface definition language for AI tools”. A government MCP server is, on closer reading, a JSON Schema deployment. We are not the only ones making this observation. When Kin Lane inventoried the API specifications stewarded by the Linux Foundation, he concluded that JSON Schema is the connective tissue across the whole catalogue: OpenAPI, AsyncAPI, CloudEvents, and others all build on it, and “JSON Schema is the substrate the other specifications are built on top of”. Taken together, public-sector use of OpenAPI and MCP rank among the largest JSON Schema deployments in the world. The rise of national schema registries If OpenAPI and MCP are both about JSON Schema, it is no surprise that governments are starting to treat schemas as their own layer, separable from any particular API specification and reusable across OpenAPI, MCP, and potentially other future consumers. They operate their schemas as standalone national assets. France runs schema.data.gouv.fr as a national multi-format schema registry. Among its JSON Schemas, the public procurement format maintained by the Ministry of Economy and Finance is used by every French state entity to publish all public contracts above €40,000. The data inclusion schema backs the national platform aggregating social-services data across France Travail, CAF, and local social services. And the cycling facilities format feeds the Base Nationale des Aménagements Cyclables, France’s mandatory contribution to the EU Regulation 2017/1926 multimodal-travel National Access Point at transport.data.gouv.fr. The schema.data.gouv.fr registry filtered to JSON Schema entries. Visible cards include the cycling-facilities format, the essential data of French public contracts, and on-street parking footprints Italy runs schema.gov.it providing JSON Schemas packaged as OpenAPI components, with each schema’s properties cross-referenced to Italian government RDF ontologies. For example, the INPS National Data Catalog publishes the JSON Schemas backing core social-security workflows: NASPI unemployment-benefit applications, pension credit purchase requests, and the A1 certificate for cross-border workers under EU Regulation 883/2004. Italy is also pioneering the IETF draft REST API Linked Data Keywords, which defines two new JSON Schema keywords for embedding JSON-LD context directly into OpenAPI and JSON Schema documents. The schema.gov.it national semantic catalogue, jointly operated by the Dipartimento per la Trasformazione Digitale and Istat, filtered to entries of type Schema The Netherlands announced in April 2026 that they are building schemas.overheid.nl, a central register for reusable JSON Schemas and OpenAPI components. The registry pattern is not confined to the G7 or the OECD. India, whose Aadhaar and UPI made it the global reference case for digital public infrastructure, initiated ONDC, the open e-commerce network incorporated by the government in December 2021, which crossed 200 million transactions in March 2025. ONDC runs on the Beckn protocol, designed by the architects of Aadhaar and UPI themselves, and the Beckn ecosystem operates its own schema registry of over 600 schema types, offered “as a public infrastructure to enable interoperable value-exchange flows”, with each concept published as an OpenAPI 3.1 component alongside its JSON Schema 2020-12 document. The same protocol is carrying the model beyond India: the ITU’s GovStack e-marketplace building block was “adapted from Beckn protocol APIs and schema”, and Beckn-based networks are live at national scale in Gambia and Nepal. The Beckn schema registry entry for DriverCandidateProfileResource, a driver recruitment concept from Beckn’s transport-hiring domain. Every concept gets a persistent canonical IRI plus versioned developer URLs for each of its faces: the OpenAPI document (attributes.yaml), the JSON-LD context, and the RDF vocabulary. Source: schema.beckn.io The rise of national schema collections One tier down, individual agencies and research bodies operate their own reusable pure JSON Schema collections, often spanning entire scientific or regulatory domains. NASA uses JSON Schema across multiple missions and platforms. It publishes JSON Schemas for the General Coordinates Network alert format. When LIGO detects a gravitational wave or Swift detects a gamma-ray burst, alerts in this format go out within seconds so observatories around the world can slew toward the source while it is still visible. NASA also maintains the Common Metadata Repository (CMR), which defines the Unified Metadata Model in JSON Schema and underpins the entire EOSDIS Earth-science catalogue. Any researcher querying NASA Earthdata for satellite imagery, climate datasets, or atmospheric measurements hits records validated against this model. The NASA General Coordinates Network Schema Browser for v7.0.0, showing mission-specific JSON Schema folders for BOOM, BurstCube, CHIME, Einstein Probe, Fermi, Glowbug, HEASARC, IceCube, KM3NeT, and others NIST publishes OSCAL, the Open Security Controls Assessment Language, as the JSON-Schema-backed control language behind NIST 800-53, NIST 800-171, NIST 800-218, and CSF v2.0. Cloud providers seeking FedRAMP authorization, defense contractors handling Controlled Unclassified Information, and any organisation aligning with the US Cybersecurity Framework can now express their entire compliance posture as JSON validated against OSCAL. The US National Cancer Institute (part of NIH) publishes the GDC Data Dictionary, 89 JSON Schemas defining every entity in the Genomic Data Commons, the federal cancer-genomics platform pooling harmonised tumour data from across NCI programmes. Every biospecimen, patient case, sequencing aliquot, mutation call, and clinical record submitted to the GDC has to validate against one of these schemas. The GDC pathology-report schema, a JSON Schema defining the structure of pathology-report records submitted to the Genomic Data Commons The UK Atomic Energy Authority publishes fusion-research metadata schemas in JSON Schema 2020-12, covering dataset, experiment, instrument, sample, and equipment records, plus dedicated schemas for the HIVE and MRF facilities. These describe data across UKAEA’s fusion programme, including the JET tokamak, MAST-U, and the upcoming STEP prototype fusion power plant targeting grid connection in the 2040s. The UK government uses JSON Schema across multiple departments. The Government Digital Service describes every content type published on GOV.UK as a JSON Schema through the publishing-api content schemas, 50+ formats covering case studies, consultations, detailed guides, document collections, fatality notices, and statistics, with every page validated against a JSON Schema before publishing. The Home Office maintains several JSON Schema repositories across its operational services, including booktravel_schema, which defines the contract between the Home Office’s Book Travel service and third-party escort and travel providers handling immigration removals. The Driver and Vehicle Licensing Agency (DVLA) has publicly described how it has “invested in tooling and processes that make heavy use of JSON Schema”, using it to describe its data models, generate human-friendly documentation, validate data, and code-generate Java and TypeScript representations of those models. JSON Schema across jurisdictions JSON Schema does not stop at national borders. When governments coordinate across jurisdictions and need to write down the shape of the data they exchange, the format they reach for is, increasingly, JSON Schema. The most consequential example is the European Digital Identity (EUDI) Wallet, the flagship digital-identity initiative under eIDAS 2.0, mandatory across all 27 EU Member States by December 2026. Its reference data model is published by the EU Wallet Consortium (EWC) as 14 versioned JSON Schemas covering the EU company certificate, IBAN attestation, signatory rights, legal-person identification, ferry boarding pass, ultimate beneficial owners, payment wallet, payment-data confirmation, personal contact details, student ID, vReceipts, person identification data, photo ID, and ID-proofing ETSI 461. The upstream W3C Verifiable Credentials Data Model 2.0, on which every national EUDI Wallet implementation depends, defines its credentialSchema property with JsonSchema as a type. The EWC consortium’s Legal Person Identification Data schema, one of the 14 JSON Schemas (2020-12) underpinning the EUDI Wallet reference data model The pattern extends beyond the EU itself. Switzerland is not a member state and is not bound by eIDAS 2.0, yet its national e-ID, approved by referendum in September 2025, independently landed on the same substrate. The Swiss Confederation’s swiyu wallet validates every credential type-metadata schema against the official JSON Schema 2020-12 meta-schema, which it ships embedded in the app, and the DID resolver of its trust infrastructure validates DID log entries against dedicated “e-ID-conform” JSON Schemas (2020-12). In the United States, NIEM (the National Information Exchange Model) plays an analogous role. NIEM 6.0 and the NIEMOpen Naming and Design Rules 6.0 were approved as OASIS Standards on 9 December 2025. The model harmonises “the 20,000+ data elements” used across US-government data exchanges (per the Book of NIEM 2025), with JSON Schema as its bindings vocabulary for JSON-encoded payloads. NIEM is used by the FBI, the Department of Defense, all 50 US states, and Employment and Social Development Canada (ESDC). Additionally, several intergovernmental research bodies publish their own JSON Schema data models, each spanning many member states. The World Meteorological Organization, a United Nations agency with 193 member states and territories, publishes WCMP2 (Core Metadata Profile 2 v2.1.0) as the JSON Schema for weather and climate metadata, with the UK Met Office among its downstream consumers. The WMO schema repository at schemas.wmo.int, served as a static directory listing of versioned schema collections including IWXXM, METCE, WaterML, WCMP, WMDR, and others. Source schemas are developed at github.com/wmo-im The European Organization for Nuclear Research (CERN), an intergovernmental body with 25 member states, runs its Open Data portal on JSON-Schema-validated records. The European Bioinformatics Institute (EMBL-EBI), the intergovernmental molecular-biology lab spanning 29 European member states, maintains a versioned JSON Schema store for biological samples. The audit: every G7, and nine of the OECD top ten Across the previous sections, we have seen many governments using JSON Schema in three ways: as standalone schema collections, inside OpenAPI specifications, and inside MCP servers. Returning to the article’s premise, every G7 member has at least one piece of JSON Schema infrastructure on the public record: Country Evidence 🇺🇸 United States api.data.gov, Code.gov metadata schema (itself a JSON Schema), NASA General Coordinates Network schemas, NASA CMR/UMM, NIST OSCAL, NCI GDC Data Dictionary, GovInfo MCP, US Census Bureau MCP, NIEM 6.0 OASIS standard with JSON Schema bindings 🇬🇧 United Kingdom UK API Catalogue, GOV.UK Notify, Open Standards Board OpenAPI 3 recommendation, GOV.UK content schemas, UKAEA fusion-research schemas, UK Home Office booktravel_schema, DVLA tooling and processes that “make heavy use of JSON Schema”, UK GDS i.AI Parliament MCP and Lex API 🇫🇷 France schema.data.gouv.fr national multi-format schema registry, data.gouv.fr MCP, #1 on the OECD OURdata 2025 index 🇩🇪 Germany bundesAPI and bund.dev community-curated catalogue documenting 60+ German federal APIs in OpenAPI. On the official side, gematik (the national health-IT body majority-owned by the Federal Ministry of Health) publishes OpenAPI specs for the e-prescription, electronic patient record, and other national health interfaces 🇮🇹 Italy api.gov.it PDND catalogue (14,672 e-services across 9,398 entities), schema.gov.it national semantic catalogue (JSON Schemas packaged as OpenAPI components), AgID OAS Checker zero-error validation gate 🇯🇵 Japan Digital Agency DS-464-2 names OAS, jgrants-mcp-server, genai-ai-api government generative AI app platform, one of the four fastest-rising scorers in OECD DGI 2025 🇨🇦 Canada Government of Canada Standards on APIs federal OpenAPI mandate (in production, for example at api.weather.gc.ca/openapi), Employment and Social Development Canada adoption of NIEM The OECD Digital Government Index 2025 top ten extends the same pattern beyond the UK (4th) and France (9th). Australia (2nd) mandates OpenAPI through NAPIDS and auto-extracts JSON Schemas from OpenAPI for the Consumer Data Right. Portugal (3rd) publishes federal OpenAPI specs through amagovpt, for example doc-SAFE. Norway (5th) ships OpenAPI through Altinn Dialogporten. Estonia (6th) describes its X-tee services in OpenAPI and catalogues them at RIHA. Ireland (7th) ships the OGCIO MessagingIE OpenAPI spec. Denmark (8th) publishes the Danish Health Data Authority NCP API in OpenAPI alongside Datafordeleren. And Chile (10th) operates Mercado Público on the JSON-Schema-based Open Contracting Data Standard. The single holdout is Korea (1st), where no public OpenAPI or JSON Schema evidence was found despite the country topping the OECD index. Beyond the OECD top 10 digital governments, the pattern continues. Switzerland, whose federal API guidelines already mandate OpenAPI, is now developing the e-government standards for its political system, covering parliamentary operations, political actors, and public consultations (eCH-0293 through eCH-0297), schema-first on the Federal Chancellery’s GitHub organisation. The eCH standards group’s stated principle is that “the data schemata are the primary artifacts”: every commit regenerates the JSON Schemas, published under government identifiers such as https://ch.paf.link/schema/operations, alongside RDF artifacts derived from the same sources. Sweden coordinates the EWC consortium behind the EUDI Wallet’s JSON Schemas, and Statistics Sweden ships its open-source Balsam research platform with the OpenAPI generator. Slovakia’s slovak-egov organisation publishes Swagger and OpenAPI specs across its national open-data catalogue and the EU’s Once-Only Technical System pilot, alongside national JSON Schemas for the Slovak DCAT-AP profile. Lithuania’s ivpk maintains national API specifications and a universal API in OpenAPI. Israel’s Ministry of Health and Colombia’s Alta Consejería TIC publish OpenAPI specifications across their respective public-sector portfolios. The Slovak DCAT-AP catalogue JSON Schema, JSON Schema 2020-12, defining the Slovak national open-data catalogue profile JSON Schema is now national infrastructure Across this article, we have seen that the G7, nine out of ten of the OECD’s top digital governments, and many others, all make use of JSON Schema. Sometimes directly, through national schema registries and cross-government data models. Sometimes indirectly, through OpenAPI specifications and MCP APIs. And this is no longer always a choice. For example, eIDAS 2.0 makes JSON Schema an EU-wide regulatory mandate. Luke Keller, chief innovation officer at the US Census Bureau, told FedScoop: "[MCP is] not the answer. It’s one of many answers." He is right. In 2026, those answers are OpenAPI and MCP. Tomorrow, they might be something else. However, the foundational layer they all sit on is the same: JSON Schema. It is the stable substrate underneath an ever-evolving stack. For this reason, France and Italy already operate national registries that support JSON Schema, and the Netherlands joined them as recently as April 2026. The US, the UK, and EU-wide initiatives like the EUDI Wallet continue to bet on JSON Schema as the format for the standalone data models they share across agencies, missions, and borders. The list will only grow.
TL;DR: Every major LLM provider (OpenAI, Google, Anthropic, Mistral, xAI, DeepSeek), the Model Context Protocol, and the AI products built on them (agent frameworks and vertical AI APIs) have all converged on the same and only schema language: JSON Schema. AI is plumbed into APIs, and APIs speak JSON AI is delivered through APIs. Every major LLM provider exposes its models behind an HTTP endpoint. AI also consumes the world through APIs: tool calls hit REST endpoints and MCP servers expose capabilities over HTTP. APIs sit on both sides of the boundary. That observation is not contested. Marco Palladino, CTO of Kong, writes: AI traffic is API traffic. Postman’s 2024 State of the API report recorded a 73% year-over-year jump in AI-related API traffic across its platform, with OpenAI alone accounting for 78.5% of it. The 2025 follow-up puts it even more directly: APIs are no longer just powering applications. They’re powering agents. Kin Lane treats AI agents as just another API consumer. And those APIs speak JSON. In Postman’s 2025 State of the API survey of 5,700+ developers, 93% reported building REST APIs, and REST APIs in practice mean JSON over HTTP. REST still dominates at 93% (Source: Postman 2025 State of the API) JSON is what application-layer software uses to move structured data between processes, services, and organisations. The format question was settled before LLMs arrived. From “please respond in valid JSON, I’m begging you” to schema-enforced generation If AI is delivered through APIs and APIs speak JSON, then naturally users wanted LLMs to talk JSON too. In 2023, getting it reliably was a notorious engineering pain. Workarounds piled up: regex extractors, assistant prefills ("Here is your JSON output: {"), multi-step prompting, repair loops, and even prompts that politely begged the model to comply. Each had its own brittle edge cases. Charlie Guo’s Stop begging for JSON is the museum tour, and captures perfectly what anyone shipping LLM features had lived through: A prompt asking the LLM to return only valid JSON, followed by the model’s mocking compliance The community treated the problem as serious enough to need dedicated infrastructure. jsonformer (~5000 stars on GitHub), an open-source library released in early 2023, opened its README by saying current approaches to this problem are brittle and error-prone. The OpenAI developer forums in 2023–2024 were full of similar threads. To solve this, OpenAI famously shipped the Structured Outputs feature in August 2024: hand the API a JSON Schema, and the model’s output is guaranteed to validate against it at the token level. No more begging, no more retry loops, no more regex extractors. The pain went from a weekly source of suffering to an API parameter. The choice of JSON Schema specifically wasn’t accidental. JSON Schema had been the de facto schema language for HTTP APIs for years. OpenAPI, the dominant API description standard, is built on top of it. AI runs on APIs. When OpenAI needed a contract language for the JSON-output problem, they naturally reached for the one API engineers already used. Structured outputs: six providers, one schema language Structured outputs proved indispensable beyond chat UIs, for any production pipeline that needed to consume LLM output programmatically. As Julien Chaumond, CTO of HuggingFace, put it: Structured generation is the future of LLMs. Within fifteen months of the first such launch, every major LLM provider had shipped equivalent support. At the time of this writing, all of them support JSON Schema. Literally all of them: Provider Launched Dialect support Notes OpenAI August 2024 Unspecified response_format with json_schema xAI / Grok December 2024 2020-12 and Draft 7 response_format with json_schema Mistral January 2025 Unspecified response_format with json_schema DeepSeek August 2025 (Beta) Unspecified Through strict-mode function calling Google Gemini November 2025 Unspecified (OpenAPI 3.0 lineage) response_json_schema parameter Anthropic November 2025 2020-12 output_config.format (and strict tool use) As an interesting data point: every provider supports JSON Schema and only JSON Schema on the wire. Not Protocol Buffers. Not Apache Avro. Not GraphQL SDL. Not even Google, despite having invented Protocol Buffers, supports it in their own AI API. But while every model now technically accepts JSON Schema, it’s not all rosy yet. Dialect commitment is uneven, with only xAI explicitly naming the ones they support. As Ben Hutton, a JSON Schema Technical Steering Committee member, writes: You wouldn’t push your code to a server where you didn’t know what version of the programming language is installed. So why is this OK for JSON Schema? And even where the dialect is named, each provider supports a different slice of the language: there are keyword gaps, varied nested-schema depth limits, and different limitations on advanced features. Even worse, the providers diverge on which features they support. For example, OpenAI supports recursive schemas but rejects allOf, while Anthropic does the opposite. The meme has evolved. Yesterday’s pain was begging for valid JSON responses. Today, we beg that a valid JSON Schema is actually accepted by every provider. LLM output constraining is hard This isn’t JSON Schema’s fault. Constraining an LLM’s output to a schema at the token level is a genuinely hard problem. Each token the model emits has to keep the output valid, and supporting more of JSON Schema’s advanced features (logical operators, dynamic referencing and polymorphism, highly circular schemas, and more) makes it even harder. And this problem is complex and important enough that an entire research subfield, constrained decoding, has formed around it. Open-source libraries like Outlines (65M+ downloads), XGrammar, and Microsoft’s llguidance made the technique practical at production scale. There is even a published academic benchmark, JSONSchemaBench, built on 10,000 real-world JSON Schemas to evaluate competing implementations. Abstract of the foundational constrained-decoding paper, Efficient Guided Generation for Large Language Models, by Brandon T. Willard and Rémi Louf, who later co-founded dottxt Even more, the authors of that paper went on to found dottxt, a French startup that raised $11.9M to solve this specific problem. Born from their popular Outlines library, dottxt aims for full LLM JSON Schema coverage and already supports far more of JSON Schema than the major providers do, allowing users to make use of JSON Schema on arbitrary models without feeling the compatibility pain. Worth noting that this problem is specific to autoregressive generation. A newer class of models sidesteps it entirely: non-autoregressive decision models that return a typed decision in a single forward pass instead of generating text. There is no token stream to constrain, so nothing needs a grammar. And yet the contract is still JSON Schema. Laya, an open-weight (Apache-2.0) model of this kind, compiles “a JSON schema (or a pydantic model)” into its own typed questions, accepting only a flat subset that rejects arrays, nested objects, and $ref recursion. Even when the hard part goes away, JSON Schema is what a new architecture reaches for to let developers declare the shape of an answer. Tool calling, and how MCP unified it LLMs are most powerful when they can connect to other systems: query databases, hit APIs, run computations, fetch documents. To do this they need a way to declare I want to call this function with these arguments, and every major provider had to ship one. Unsurprisingly, they all landed on the same answer: define the tool’s input as JSON Schema. OpenAI’s parameters, Anthropic’s input_schema, Gemini’s function_declarations. Different field names, identical substrate. Then MCP (Model Context Protocol) came along to unify it. Announced by Anthropic in November 2024 and built on JSON Schema 2020-12, MCP is to AI agents what OpenAPI is to HTTP APIs: a single shared way to describe tools so any model can discover and invoke them. OpenAI’s official adoption in March 2025 was the inflection point. Monthly SDK downloads jumped from around 8 million to 22 million within weeks. Google DeepMind, Microsoft, Meta, Cursor, Windsurf, JetBrains, Replit, and ChatGPT desktop followed. In December 2025, Anthropic donated MCP to the Linux Foundation, the same body that governs OpenAPI and AsyncAPI. One year of MCP: spec releases, ecosystem milestones, and adoption highlights, from the November 2024 launch to the December 2025 Linux Foundation donation. From Anthropic The adoption is substantial. By March 2026, MCP SDKs had reached 97 million monthly downloads, with 13,700+ servers on PulseMCP alone and 300+ MCP clients across editors, chat apps, and enterprise platforms. The business case is concrete. Block reports 50–75% time savings on common tasks for thousands of employees using their MCP-compatible Goose agent. Microsoft’s Sales Development Agent recorded a 15.1% increase in lead-to-opportunity conversion across 61,734 leads. Zapier’s MCP server connects 9,000+ apps with 30,000+ actions. The entire LLM tool ecosystem now builds on JSON Schema too. And the whole AI stack speaks JSON Schema Beyond the LLM APIs and the MCP/tools layer, the JSON Schema foundation extended naturally upward to the AI products built on top. Here is a non-exhaustive list: Retab. Document AI platform with $3.5M pre-seed backed by Eric Schmidt and the CEOs of Datadog and Dataiku, with 500M+ documents processed. Their SDK literally takes a json_schema argument LandingAI. Andrew Ng’s document AI company. Their Agentic Document Extraction takes JSON Schema as its extraction format, with documented support for standard JSON Schema keywords and format values Vapi. Voice AI agent platform. Custom tool definitions take a JSON Schema as the parameters field AssemblyAI. Speech and transcript understanding. Their LLM Gateway exposes response_format with json_schema, OpenAI-compatible Firecrawl. Web scraping and extraction. The schema parameter takes a JSON Schema describing the structured output to extract from a page Tavily. Deep research API. The output_schema parameter is “a JSON Schema object that defines the structure of the research output” Above the products sit agent frameworks: the libraries and tools developers use to build programs that compose LLMs with tools, memory, and control flow to decide for themselves which actions to take. Unsurprisingly, every major one uses JSON Schema as the contract between the model and the tools it can invoke: LangChain. The dominant Python agent framework CrewAI. Multi-agent orchestration OpenAI Agents SDK. OpenAI’s first-party agent framework Microsoft Semantic Kernel. Microsoft’s framework supporting .NET, Python, and Java Mastra. TypeScript-first agent framework Vercel AI SDK. The dominant Next.js AI integration layer Composio. Tool-integration platform with hundreds of pre-built integrations None of these products coordinate on which schema language to use. They independently arrived at the same answer to the same problem, making JSON Schema the contract at every layer of the stack. Even the exception isn’t quite an exception: the A2A hybrid case You would expect at least one exception to this convergence. Google has every reason to push Protocol Buffers in their AI infrastructure. So when Google designed A2A (Agent-to-Agent), an open protocol for AI agent-to-agent communication, they made Protocol Buffers the “single authoritative normative definition” of the spec. End of story? Not quite. Look at how A2A actually works on the wire and JSON Schema is still everywhere. Agents communicate using JSON-RPC 2.0 over HTTP. The wire format is JSON, not binary Protocol Buffers. The spec already generates a JSON Schema at build time out of the Protocol Buffers definition, and the authors plan to add an OpenAPI v3 bundle on top for enhanced tooling. You can explore these schemas at schemas.sourcemeta.com. The A2A Protocol schemas in Sourcemeta Schemas So even where Protocol Buffers wins as the authoring source, JSON Schema wins as the interoperability substrate. Charlie Holland captures the pattern precisely: “JSON Schema becomes the ‘assembly language’ of schema definitions” and higher-level languages compile down. The exception confirms the rule: convergence on JSON Schema is not just visible at the LLM layer. It reaches even into the protocols designed to avoid it. The schema layer deserves its own infrastructure JSON Schema was first proposed in 2007 as a way to annotate JSON documents. Nobody designed it for AI. It quietly became the dominant API-spec substrate over a decade and a half. The AI industry did not pick JSON Schema. It found that JSON Schema had already been picked, by seventeen years of accumulated convention, and built on top. As Charlie Holland frames it, JSON Schema has become the interface definition language for AI tools. The implication for anyone building APIs or AI-facing software is direct. Your schema layer is no longer documentation. It is the interface AI systems will use to consume your software. And the demand for that interface is already universal. After auditing 989 Fortune 1000 companies, Kin Lane found zero without an AI signal: The signal floor is non-zero across every industry in the Fortune 1000, including the ones I expected to come up empty. Mining. Tobacco. Specialty retail. And the next layer of that interface is already taking shape: governance. Portkey’s review of production MCP deployments catalogues the security and trust gaps now surfacing across the ecosystem, and points at a familiar model for closing them: A better reference is JSON-schema-based registries used in major cloud platforms, where structure and validation are enforced.
TL;DR: We analysed thousands of real-world OpenAPI specifications and found that in 76% of modern OpenAPI 3.x specs with a typed data model, JSON Schema is the majority of the file. In the best-known APIs, it routinely exceeds 80%. The schema layer is the substance of every API contract, yet almost no tool is positioned accordingly. OpenAPI is, by every reasonable measure, the dominant standard for describing HTTP APIs. It is a Linux Foundation project whose founding members include Google, Microsoft, IBM, Capital One, and PayPal. Today the OpenAPI Initiative counts more than 30 corporate members, and the standard is the de-facto contract used by Stripe, GitHub, Mailchimp, Vercel, Slack, Twilio, Zoom, AWS, Azure, Google Cloud, and effectively every other organisation that takes its public APIs seriously. What is much less well known is that most of an OpenAPI document is not, strictly speaking, OpenAPI at all. It is JSON Schema. OpenAPI is the chassis, JSON Schema is the engine OpenAPI provides the structure for describing HTTP endpoints: paths, methods, parameters, responses, security, servers. But the actual work of describing what data flows in and out of those endpoints is delegated to the standard OpenAPI builds on top of: JSON Schema. In fact, request bodies, response payloads, query parameter types, header constraints: each of these is defined as a JSON Schema. In case you haven’t seen an OpenAPI spec, this is how a trivial one defining a single endpoint looks like: openapi: 3.1.0 paths: /pets/{id}: get: parameters: - name: id in: path required: true # This is a JSON Schema schema: type: string format: uuid responses: "200": content: application/json: # This is a JSON Schema schema: type: object required: [ id, name ] properties: id: type: string, format: uuid name: type: string minLength: 1 This layering is not an OpenAPI quirk. When Kin Lane inventoried every API specification stewarded by the Linux Foundation, he found that JSON Schema is the connective tissue of the entire catalogue: The deeper I looked, the more one thread kept showing up underneath everything else: JSON Schema. OpenAPI uses it. Arazzo and Overlay use it. AsyncAPI uses it. CloudEvents ships a JSON Schema. OSV and SPDX lean on it. The OpenAPI metaschema is JSON Schema. […] JSON Schema is the substrate the other specifications are built on top of. Let’s measure how big the engine is We analysed 4,127 real-world API specifications from the APIs-guru/openapi-directory repository, the largest curated dataset of public OpenAPI documents. The dataset is no longer actively maintained, but it remains the de facto industry corpus, still used in the test suites of well-known tools like Speakeasy. The dataset and analysis script is open-source for anyone wishing to reproduce or extend these results. Across all 4,127 specifications and 17.6 million lines of YAML, 54.3% of the content is JSON Schema, and if we restrict the analysis to OpenAPI 3.x specifications (modern specs), the median rises to 61%. Overall, in 76% of these specifications, JSON Schema is the literal majority of the file. More concretely, we can conclude that: in 76% of modern OpenAPI specifications, JSON Schema dominates the specification. Distribution of schema percentage across OpenAPI 3.x specifications with schemas. The 50% threshold is shown as a dashed line, 76% of the distribution sits to the right of it. The trend is towards more schema, not less Comparing Swagger 2.0 to OpenAPI 3.x is interesting. The median Swagger 2.0 spec is 39% schema, while the median OpenAPI 3.x spec is 60%. That is certainly not because the format suddenly enabled more schema content, but because OpenAPI 3.x specifications were typically written more recently. For context, Swagger 2.0 was the dominant format from roughly 2014 to 2017. OpenAPI 3.x took over from 2018 onwards. The ~21% jump is the industry learning, year over year, that schemas matter. The same pattern shows up when we segment by API maturity. Specifications with fewer than 10 reusable type definitions have a schema-to-non-schema ratio of around 0.65:1. Specifications with more than 250 type definitions have a ratio of 1.79:1. As APIs grow and stabilise, schema takes over. Schema-to-non-schema ratio plotted against the number of reusable type definitions per spec. The ratio crosses the 1.0 threshold (where schema equals everything else combined) around the 25 to 50 type-definition range, and keeps climbing. The best-known APIs are almost entirely schema If you sort the well-known providers in the dataset by how much of their specification is JSON Schema, the top of the list is striking: Schema percentage in the top five well-known APIs by schema content. Mailchimp leads at nearly 94%, with Vercel, Stripe, Zoom and Adyen all above 64%. The companies known for taking their developer experience seriously sit at the top of the list. It is reasonable to conclude that the providers who invest most heavily in API quality also tend to invest more heavily in rich formal type definitions. Likely for the purpose of documentation generation, SDK generation, contract testing, and more. Two ways the industry hides the schema layer If JSON Schema is the substance of the API contract, you would expect the tooling ecosystem to be built around it. But It is not. The schema layer loses in two distinct ways: it disappears when tools handle it well, and it goes unnoticed when tools handle it poorly. When schema work is done well, nobody notices Take Speakeasy, one of the leading commercial SDK generators in the space. Their product is excellent, and to do its job well it has to do substantial JSON Schema engineering for code-generation purposes. By volume, most of what their generator does end-to-end is schema work, because most of the spec is schema. And yet the product positions itself as “OpenAPI native”. This is not a Speakeasy critique. The same pattern shows up across most SDK generation, design, and documentation tools: the schema work is being done, often very well, but the product surface presents it as OpenAPI work. The irony is that the customer is led to think of their work as OpenAPI work, when most of it is schema work. And so they never consider the schema layer as a layer in its own right. When schema work is done poorly, nobody notices either Take Prism, a popular tool for mocking and contract-testing APIs against their OpenAPI specs. Doing that job means validating real request and response payloads against the schemas in the spec, which means the validator under the hood is the substance of what the tool does. Prism ships with AJV, a popular JavaScript JSON Schema validator. The bad news is that AJV is consistently one of the least compliant implementations of JSON Schema around, as proven by the official Bowtie cross-implementation conformance tool. At the time of this writing, AJV lists 254 failures on the version of JSON Schema that OpenAPI 3.1 itself uses. The practical consequence is more insidious than a broken test. Either Prism rejects payloads that are perfectly valid against your schemas, pushing you to weaken your spec until Prism is happy, or worse, Prism accepts payloads that your schemas should reject, pushing you to ship an implementation that quietly disagrees with what your spec actually says, causing even more subtle drift. The irony is that Prism is part of SwaggerHub, the flagship platform of SmartBear, the very company that created the Swagger project. If the creators of the wrapper format ship a tool that mishandles the substance inside the wrapper, what hope is there for the rest of the industry? The schema layer deserves its own infrastructure If JSON Schema is the substance of your API contract, and if the schema content of your APIs is going to keep growing as your APIs mature, then the schemas deserve their own infrastructure: correct implementations, a cohesive API-first registry, a governance model, a discovery mechanism, and tooling that understands them as semantic objects rather than as opaque sections within a YAML file. Kin Lane arrives at the same conclusion from the standards side: “there is no reason a CloudEvent’s schema, an AsyncAPI message, and an OpenAPI body could not lean on the same JSON Schema tooling and the same registry patterns”. The data says the schema layer is already most of your API. The question is whether you treat it that way.