Fully solving JSON Schema and JSON-LD interoperability

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.
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.
And here is an order payload, one company selling to one individual, the kind that would flow through a commerce API:
Now let’s run this through the Sourcemeta JSON Schema CLI:
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:
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:
You can convert to JSON-LD emitting the shape your consumers already know how to parse, with its semantics embedded, as follows:
In other words, the context is your choice of projection. The schema annotations remain the single source of truth.
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.
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 Grap