---
type: "article"
title: "Fully solving JSON Schema and JSON-LD interoperability"
summary: "TL;DR: The same JSON Schema that validates\nyour data can now declare what that data means. We built a ten-keyword\nextension vocabulary (x-jsonld-*) that promotes instances to\nJSON-LD (the JSON serialisation of\nRDF). Annotate the schemas you already have, and\nevery payload they validate becomes knowledge-graph-ready. Over the past\ndecade, everyone from\nMuleSoft to\nAdobe to\nthe Italian\ngovernment\nattempted some version of this bridge, and every attempt fell short of the\nsame hard part: composition. We solved it, and it ships today in the JSON\nSchema\nCLI\nand in the Sourcemeta One registry.\nThere is a fair chance JSON-LD lives in your head as\n“the schema.org blob you paste into a web page so Google\nshows rich\nresults”.\nBut JSON-LD is much more than that. It is\none of the credential formats the EU Digital Identity\nWallet accepts, which all 27 member\nstates must ship by December 2026. It is the foundation of Microsoft’s Digital Twins\nDefinition\nLanguage.\nIt is how hundreds of thousands of machine-learning\ndatasets\ndescribe themselves on Hugging\nFace and\nKaggle, how all of EU\nlaw is published, and how\nwebsites talk to AI\nagents.\nJSON-LD is what JSON looks like when it graduates into a\nknowledge\ngraph.\nAnd yet, from where the JSON Schema world sits,\nJSON-LD might as well be on another planet. It does not\nmatter which door brought you to JSON Schema: OpenAPI specifications (76% of\nthe modern ones are majority JSON Schema by\nvolume),\nAsyncAPI message payloads, MCP tool\ndefinitions, W3C\nWeb of Things Thing\nDescriptions, the\nIETF’s Semantic Definition\nFormat for the\nInternet of Things, or plain standalone data models of the kind governments\nnow publish in national\nregistries. Sooner\nor later the same need appears: joining JSON\nSchema’s validation strengths with\nJSON-LD’s semantic strengths.\nThe rest of this article covers how the two languages each won their own layer\nof the data world, who tried to bridge them over the past decade, where every\nattempt fell short, and how we made it work.\nOur JSON-LD extension vocabulary\nWe built the bridge as a JSON Schema extension\nvocabulary: ten annotation keywords under the x-jsonld- prefix, deliberately\ncontinuing the convention introduced by the Italian government’s REST API\nLinked Data Keywords IETF\ndraft.\nBecause the keywords are plain x- extensions rather than a formal JSON\nSchema\nvocabulary,\nannotated schemas remain valid for every implementation, including the many\nwith no vocabulary support at all.\nHere is a schema that describes a\nschema.org/Order whose seller and customer\nreuse a single party definition through\n$ref, where a party\nreuses a shared address, and where a party is a\nschema.org/Person or a\nschema.org/Organization depending on its\nkind.\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"type\": \"object\",\n  \"x-jsonld-type\": \"https://schema.org/Order\",\n  \"properties\": {\n    \"orderNumber\": {\n      \"type\": \"string\",\n      \"x-jsonld-id\": \"https://schema.org/orderNumber\"\n    },\n    \"seller\": {\n      \"$ref\": \"#/$defs/party\",\n      \"x-jsonld-id\": \"https://schema.org/seller\"\n    },\n    \"customer\": {\n      \"$ref\": \"#/$defs/party\",\n      \"x-jsonld-id\": \"https://schema.org/customer\"\n    }\n  },\n  \"required\": [ \"orderNumber\", \"seller\", \"customer\" ],\n  \"$defs\": {\n    \"party\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"kind\": { \"enum\": [ \"person\", \"organization\" ] },\n        \"name\": { \"type\": \"string\", \"x-jsonld-id\": \"https://schema.org/name\" },\n        \"address\": {\n          \"$ref\": \"#/$defs/address\",\n          \"x-jsonld-id\": \"https://schema.org/address\"\n        }\n      },\n      \"required\": [ \"kind\", \"name\" ],\n      \"if\": { \"properties\": { \"kind\": { \"const\": \"person\" } } },\n      \"then\": { \"x-jsonld-type\": \"https://schema.org/Person\" },\n      \"else\": { \"x-jsonld-type\": \"https://schema.org/Organization\" }\n    },\n    \"address\": {\n      \"type\": \"object\",\n      \"x-jsonld-type\": \"https://schema.org/PostalAddress\",\n      \"properties\": {\n        \"country\": {\n          \"type\": \"string\",\n          \"x-jsonld-id\": \"https://schema.org/addressCountry\",\n          \"x-jsonld-self\": \"http://publications.europa.eu/resource/authority/country/{this}\"\n        }\n      }\n    }\n  }\n}\n\n\nAnd here is an order payload, one company selling to one individual, the kind\nthat would flow through a commerce API:\n{\n  \"orderNumber\": \"AC-2026-0042\",\n  \"seller\": {\n    \"kind\": \"organization\",\n    \"name\": \"ACME GmbH\",\n    \"address\": { \"country\": \"DEU\" }\n  },\n  \"customer\": {\n    \"kind\": \"person\",\n    \"name\": \"Erika Mustermann\",\n    \"address\": { \"country\": \"ITA\" }\n  }\n}\n\n\nNow let’s run this through the Sourcemeta JSON Schema\nCLI:\n$ jsonschema rdf schema.json instance.json\n\n\nBoth parties come out of the same\n$ref with different\nRDF types, the seller an\nOrganization and the customer a\nPerson, each carrying an address typed as a\nschema.org/PostalAddress with its country\npromoted to the EU country\nauthority IRI:\n[\n  {\n    \"@type\": [ \"https://schema.org/Order\" ],\n    \"https://schema.org/orderNumber\": [ { \"@value\": \"AC-2026-0042\" } ],\n    \"https://schema.org/seller\": [\n      {\n        \"@type\": [ \"https://schema.org/Organization\" ],\n        \"https://schema.org/name\": [ { \"@value\": \"ACME GmbH\" } ],\n        \"https://schema.org/address\": [\n          {\n            \"@type\": [ \"https://schema.org/PostalAddress\" ],\n            \"https://schema.org/addressCountry\": [\n              { \"@id\": \"http://publications.europa.eu/resource/authority/country/DEU\" }\n            ]\n          }\n        ]\n      }\n    ],\n    \"https://schema.org/customer\": [\n      {\n        \"@type\": [ \"https://schema.org/Person\" ],\n        \"https://schema.org/name\": [ { \"@value\": \"Erika Mustermann\" } ],\n        \"https://schema.org/address\": [\n          {\n            \"@type\": [ \"https://schema.org/PostalAddress\" ],\n            \"https://schema.org/addressCountry\": [\n              { \"@id\": \"http://publications.europa.eu/resource/authority/country/ITA\" }\n            ]\n          }\n        ]\n      }\n    ]\n  }\n]\n\n\nThe seller and customer were typed differently from the same definition, and\nthe address mapping, written once, applied to both, because the annotations\ncompose through $ref\nexactly as validation does. One schema. One pass. If the instance is invalid,\nno RDF comes out at all. That output is in standard\nJSON-LD expanded\nform, canonical and\ncontext-free.\nIf you would rather keep the document looking like the JSON your\nconsumers already parse, compact it against a context of your choosing. For\nexample, consider this context.json:\n{\n  \"@context\": {\n    \"schema\": \"https://schema.org/\",\n    \"orderNumber\": \"schema:orderNumber\",\n    \"seller\": \"schema:seller\",\n    \"customer\": \"schema:customer\",\n    \"name\": \"schema:name\",\n    \"address\": \"schema:address\",\n    \"country\": {\n      \"@id\": \"schema:addressCountry\",\n      \"@type\": \"@id\",\n      \"@context\": { \"@base\": \"http://publications.europa.eu/resource/authority/country/\" }\n    }\n  }\n}\n\n\nYou can convert to JSON-LD emitting the shape your consumers already know how\nto parse, with its semantics embedded, as follows:\n$ jsonschema rdf schema.json instance.json --compact context.json\n\n\n{\n  \"@type\": \"schema:Order\",\n  \"orderNumber\": \"AC-2026-0042\",\n  \"seller\": {\n    \"@type\": \"schema:Organization\",\n    \"name\": \"ACME GmbH\",\n    \"address\": { \"@type\": \"schema:PostalAddress\", \"country\": \"DEU\" }\n  },\n  \"customer\": {\n    \"@type\": \"schema:Person\",\n    \"name\": \"Erika Mustermann\",\n    \"address\": { \"@type\": \"schema:PostalAddress\", \"country\": \"ITA\" }\n  },\n  \"@context\": {\n    \"schema\": \"https://schema.org/\",\n    \"orderNumber\": \"schema:orderNumber\",\n    \"seller\": \"schema:seller\",\n    \"customer\": \"schema:customer\",\n    \"name\": \"schema:name\",\n    \"address\": \"schema:address\",\n    \"country\": {\n      \"@id\": \"schema:addressCountry\",\n      \"@type\": \"@id\",\n      \"@context\": { \"@base\": \"http://publications.europa.eu/resource/authority/country/\" }\n    }\n  }\n}\n\n\nIn other words, the context is your choice of projection. The schema\nannotations remain the single source of truth.\nJSON-LD and the knowledge graph economy\nLook again at what came out of that command. The expanded form is\nJSON-LD, which is the JSON serialisation of\nRDF, the W3C’s model for\ndescribing anything as a graph of subject-predicate-object (triple) statements.\nBuild enough of those statements and you have a knowledge graph. The idea is\nsimple: give every thing (such as a person, a country, a product, etc) one\nshared identifier, and record every fact as a link between those identifiers.\nDo that, and data scattered across systems, formats, and organisations becomes\na single connected web that anyone, and any machine (including AI), can query\nacross sources and reason over as a whole. That is the door our example\nquietly opened, and it leads somewhere very large.\nAlmost everything you would call authoritative knowledge is already living in\nthis way. Wikidata holds 1.65 billion\nstatements. UniProt, the reference database of\nprotein knowledge, exposes over 190 billion\ntriples through what\nis widely cited as the largest public\nSPARQL endpoint on earth, and the US\nNational Institutes of Health\npublishes its PubChem chemistry database as more than 130 billion triples of\nits own. Both are nodes in a life-sciences web that interlinks through the\nLinked Open Data cloud and its 1,658 connected\ndatasets. Governments are wired\nthe same way: every EU legal act is\nRDF behind a public\nendpoint, and France’s statistics office, its\nnational library, and\nEuropeana’s 50 million cultural objects all publish\nin it. Healthcare does the same through HL7\nFHIR, which defines an RDF form for the\nrecords it moves between systems. So does big tech: Google, Microsoft,\nFacebook, eBay, and IBM each run their\nown. And it\nis how AI now gets its facts, since a model on its own is a parametric memory\nthat hallucinates and the fix is to\nground it in a graph, the pattern behind\nGraphRAG.\nFrance’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.\n  \n\nNone of them do this for tidiness. They do it because the graph is where data\nturns into value. We know that data is a valuable asset, but raw data is worth\nonly what you can refine it into, and the knowledge graph is the refinery. When\nGoogle launched its Knowledge Graph in\n2012 under the\nslogan “things, not strings”, search stopped matching text and started\nunderstanding entities. By 2016, Google reported that it held 70 billion facts\nand answered roughly a third of its 100 billion monthly\nsearches straight from\nit. The mechanism is\nRDF’s shared identifiers. They allow independently\nproduced data to become joinable, so the graph is worth more than the databases\npoured into it, and every entity added compounds the value of the ones already\nthere. And this compounding now has a price. A data.world\nbenchmark measured a language model at 16%\naccuracy over a raw SQL database and 54% over the same data as a knowledge\ngraph.\nGartner\nfinds the organisations with the most mature data foundations achieve up to 65%\ngreater business outcomes. And the knowledge graph market is projected to grow\nfrom $1.06 billion in 2024 to $6.93 billion by\n2030.\nBridging JSON Schema and JSON-LD\nZooming out, structure and meaning are things you constantly need at once, and\ntoday they live in different languages. JSON Schema\nowns structure, whether the container is an OpenAPI\nspecification,\nan AI tool\ndefinition, or a\nnational data\nregistry. Then,\nJSON-LD owns meaning, as the last section showed. The\ncatch is that a single JSON document routinely needs both at once, and inside\nthat document the two languages cannot see each other. A JSON\nSchema cannot say that family_name means\nschema.org/familyName, and a\nJSON-LD context cannot say that family_name is a\nrequired string conditional on the presence of first_name.\nA 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.\n  \n\nNow picture closing that gap. For example, the EU wallet\nschema\nalready validates every credential a wallet API handles. Put the meaning inside\nit, and that one file also emits the knowledge graph. No second artefact to\nauthor, review, version, or keep in sync. The meaning is defined exactly once\nnext to its validation constraints, and every payload pours into the graph for\nfree. In other words, intermixing JSON Schema and JSON-LD gives the\nRDF world a powerful validation story, and it gives\nthe JSON Schema world a significant upgrade in\nsemantics and knowledge graph integration.\nThe reason to state the prize so plainly is that the alternative, two artefacts\nkept in sync by hand, is everywhere, and it is a heavy tax. The Common\nWorkflow Language project named it in 2015, when it\nabandoned existing schema languages because “none understand linked\ndata”:\n“one must maintain separate JSON schema, JSON-LD context, RDF schema, and\nhuman documentation, despite significant overlap of content and obvious\nneed for these documents to stay synchronized.”\nA decade later that tax is institutional:\nW3C Verifiable Credentials\n2.0: the standard beneath the EU\nwallet, carries a JSON-LD @context for meaning and a\nseparate credentialSchema for\nstructure in every single credential. It takes a whole\nappendix\nto hold the two apart, a credentialSchema defining “the contents and\nstructure of a set of claims” while a @context is “best used only for\nconveying the semantics and term definitions of the data”, and it takes the\ntwo “used in combination” before “both producers and consumers can be more\nconfident about the expected contents and data types”. Nothing links them,\nso the companion specification can only advise the\nauthor:\n“It is advised to associate all properties that have a semantic mapping with\na property in a credential schema.” That advice is the entire binding, and\nimplementations show what it is worth.\nCredo, the OpenWallet\nFoundation’s wallet framework, ships the whole JSON-LD stack down to RDF\ncanonicalisation and nineteen hand-authored context\ndocuments,\nwhile credentialSchema is modelled as an id and a\ntype\nthat it never fetches or evaluates.\nWE BUILD: one of the\nEU-co-funded Large Scale Pilots now building that wallet, keeps its credential\nJSON\nSchemas\nin one repository owned by one working group, while a second\ngroup\nhand-maintains the SKOS terminology, OWL vocabulary, and JSON-LD\ncontext\nin another. Nothing in the schemas points at the vocabulary, so the mapping\nbetween them survives in a third artefact: a Markdown table in the\nhuman-readable\nrulebook,\nunder a column headed “Semantic Reference”, recording that family_name\nmeans w3id.org/ebwv#familyName while\nthe schema next\ndoor\ncan only call it a string.\nGS1’s EPCIS: the global supply-chain\nstandard, ships EPCIS-JSON-Schema.json and epcis-context.jsonld side by\nside in one repository.\nFIWARE’s Smart Data\nModels: keep a schema\nfor every entry in the catalogue, paired with a JSON-LD context.\nGaia-X:\nEurope’s flagship cloud-federation project, pairs a\nJSON-LD self-description with a separate SHACL shape\nfor every participant.\nBeckn: the open-commerce protocol from the architects\nof India’s Aadhaar and UPI, and the backbone of India’s government-backed\nONDC network and its 200 million\ntransactions,\ngoes further still: it normatively\nrequires\nevery one of the 300+ concepts in its schema\nrepository to ship four artefacts side by\nside, an OpenAPI envelope, a JSON Schema, a JSON-LD context, and an RDF\nvocabulary.\nAdobe:\nspecified its Experience Data Model in both grammars at once, then had to\nbolt on a “Compatibility\nMode”\nthat flattens the JSON-LD namespacing out for its own\nplatform.\nAnd the request to fix this at the source has sat open on the JSON Schema\nissue tracker since April\n2017.\nEveryone pays the tax. Nobody has figured out how to fully remove it.\nThe double edge of expressiveness\nSo now you might wonder, with the prize this clear and the demand this old, why\nhas this stayed unsolved?\nBecause the obvious fix, embed the @context in the schema, only works on the\neasy case. That is what the Italian government’s REST API Linked Data\nKeywords IETF\ndraft does.\nThis is often enough for standalone simple schemas. But in practice, schemas\nare very often not standalone, and very often not simple. At scale, models of\nrich cross-referenced schemas are extremely common for schema reusability and\ndata governance purposes.\nWhat makes it hard to solve this for complex schemas is the very thing JSON\nSchema is best at. JSON Schema is a remarkably expressive\nlanguage. The meaning of a\nproperty can be split across files with\n$ref, combined through\nlogical applicators like\nanyOf, or made\nto depend on the data in complex ways through\nif/then/else,\nand other similar keywords. With\n$dynamicRef a\nschema even resolves a reference differently depending on the context it is\nevaluated in, so there is no static document to analyse ahead of time and the\nmeaning is decided during evaluation, against the data. This is why validating\nModern JSON Schema is PSPACE-complete. In\ncomparison, a JSON-LD context has none of this. It is a\nflat table of names, and it cannot follow a schema whose properties change\nmeaning by position or by data. It could never, for instance, produce the order\nfrom our example, where the very same party definition became a\nPerson or an\nOrganization depending on a property in\nthe payload.\nIf you take this as a criticism, that JSON Schema is simply too complicated, you\nhave it backwards. The complexity is not over-engineering. It is the language\nearning its keep. Most people who resent JSON Schema for its constraint-driven\ncomplexity have simply not yet met the problems that demand such complexity.\nAnd when they do, they are thankful that the expressiveness exists.\nA decade of attempts\nBut all of that expressiveness is what a bridge to\nJSON-LD has to carry across, and it is why no one had\nbuilt one that holds. Everyone who tried faced the same fork: strip the\nexpressiveness away so the mapping to RDF turns\neasy, or keep it and try to pay the price. A decade of attempts went both ways,\nand came up short in both cases.\nThe strippers made the problem vanish by not having it. The Common Workflow\nLanguage’s Schema Salad\nrebuilt the schema language on top of Avro, while\nLinkML and the\nautomotive industry’s\nCatena-X\ngenerate JSON Schema from a separate RDF model you must author first. This\npath has real public-sector uptake: Switzerland’s\neCH e-government standards group authors the data\nstandards for the Swiss political system in LinkML precisely so that JSON\nSchema and OWL can be regenerated side by side on every\ncommit, further proof\nof how badly the two worlds need each other. A simpler\nlanguage projects into RDF more cleanly, but simplicity is the price: you\nsurrender the conditionals and constraints that are the reason to reach for\nJSON Schema at all, and that no other mainstream schema language\nmatches. “Those languages define\nstructure”, as Charlie Holland puts it, while “JSON Schema defines structure\nand constraints”.\nThe embracers kept JSON Schema and hit the wall head-on. The Open Geospatial\nConsortium’s tooling assembles\nthe context from the schema at build time, and its own source carries a\nthirty-line comment about “binding\nbubbling”,\nwhere a referenced schema’s mappings silently overwrite the parent’s. India’s\nBeckn walks the same path today: its generator\nscripts scrape property\nnames out of a schema and map each one to a flat beckn: IRI, blind to\n$ref (in one typical\nconcept,\nfour of the five terms in the published context sit behind references the\ngenerator cannot see), which is why the repository also carries scripts named\nschema_parity_audit.py and identify-and-fix-missing-context-vocab.py to\npatch the artefacts back into agreement.\nThe credential world built the same thing and stopped in the same place:\nschemasToContext,\nfrom Transmute, which holds an editor’s seat on\nthe VC JSON Schema specification,\nreads $linkedData annotations off a schema’s properties and flattens them\ninto a context, and that design is the ecosystem’s convention: Hedera’s\nGuardian vendors the file itself, and\nthe W3C CCG traceability\nvocabulary\nbuilds its context from its own copy of the same design. Each reads a single\nlevel of properties and resolves no\n$ref, leaving the caller\nto hand over every subschema up front, and Transmute’s source marks where it\nstops with a commented-out stub: // Need to handle anyOf and oneOf better....\nOthers went sideways:\nMuleSoft validated existing\nJSON-LD with JSON Schema before being archived at “pre-alpha”, and\nRML and the AI-assisted\nMetaConfigurator add a third artefact to\ndrift from the other two. Even\nAdobe and\nAutodesk\ntook runs at this JSON Schema and JSON-LD interoperability problem.\nHow 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.\n  \n\nFive ways to fall short\nFor all their differences, the attempts share the same gaps. None couples\nvalidation and emission in one pass. None reproduces the composition inside the\nschema itself, and the closest do it as a lossy build step. None handles\nconditional meaning, and none mints identifiers from the data.\nThe most serious attempt is telling in where it came from. Italy runs both\nworlds at national scale: a network of RDF\nontologies\nthat models its public administration as a knowledge graph, and a national\nplatform of services\ndescribed in OpenAPI and JSON Schema. It felt the collision before anyone else\nand set out to close it.\nItaly’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.\n  \n\nEven so, Roberto Polli’s REST API Linked Data Keywords IETF proposal for this\nproblem\n(now at its ninth revision) admits the limit:\n“Automatic composability is not an explicit goal of this specification\nbecause of its complexity. […] These issues can be tackled in future\nversions of this specifications.”\nAgainst what a working solution actually needs, the pattern is stark:\nAttempt\n\t\t\t\t\tStandard JSON Schema\n\t\t\t\t\tSingle evaluation pass\n\t\t\t\t\tComposition\n\t\t\t\t\tConditional meaning\n\t\t\t\t\tIRI minting\n\t\t\t\nPolli draft (embed context)\n\t\t\t\t\tyes\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\nOGC (generate context)\n\t\t\t\t\tyes\n\t\t\t\t\tno\n\t\t\t\t\tpartial\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\nTransmute, W3C CCG traceability (generate context)\n\t\t\t\t\tyes\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\nSchema Salad (new language)\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tpartial\n\t\t\t\nLinkML / Catena-X, automotive (separate model)\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\nMuleSoft, Salesforce (validate JSON-LD)\n\t\t\t\t\tpartial\n\t\t\t\t\tno\n\t\t\t\t\t$ref only\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\nRML / MetaConfigurator (mapping)\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tyes\n\t\t\t\nAdobe XDM (maintain both by hand)\n\t\t\t\t\tpartial\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\nBeckn / ONDC, India’s DPI (four parallel artefacts)\n\t\t\t\t\tyes\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\t\tno\n\t\t\t\nSourcemeta\n\t\t\t\t\tyes\n\t\t\t\t\tyes\n\t\t\t\t\tyes\n\t\t\t\t\tyes\n\t\t\t\t\tyes\n\t\t\t\nAfter a decade of attempts, from academic prototypes to Adobe, Salesforce, and\nthe automotive industry, the wall was still standing. That is where we come in.\nHow we cracked it\nSo how do you carry all of that expressiveness into\nRDF? Every prior attempt treated the schema as a\ndocument to be parsed and mapped. We treat it as a program to be run.\nSourcemeta maintains Blaze, a\nhigh-performance C++ JSON Schema\nvalidator that compiles a\nschema into a low-level program and executes it against an instance. Around\nthat execution we built a full custom JSON-LD engine\nthat rides along, producing the RDF in lockstep with\nthe validation itself. So the meaning is built during evaluation, as part of\nthe process, and the dynamism that defeated every static approach is carried by\nthe run instead of fought.\nThe result is full support for every construct JSON Schema has, in one file and\none pass, with no second artefact to drift. The order from our initial example,\nwhich no prior tool could produce due to its use of some advanced keywords, is\nnot a special case. It is simply what the engine does. If a schema can validate\nyour data, it can now describe what that data means.\nUse it today\nThe vocabulary is ten keywords under the x-jsonld- prefix, and the CLI\ndocumentation\nis for now the full reference (we are aiming for a proper spec around it soon).\nYou can use it today from the command line by pointing jsonschema rdf at\na schema and an instance, and get JSON-LD back, exactly\nas we did above.\nThe 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\n  \n\nBut the command line is the small version of the idea. The same engine ships in\nSourcemeta One, our flagship schema\nregistry, where it runs over HTTP. Every schema the registry governs can turn\nan instance into JSON-LD on request, making meaning an\nAPI call (available through MCP too).\nWith this, you can send your data to the registry and know what that data\nmeans, resolved against the schemas your organisation has already agreed on, so\nthe transformation happens once, at the infrastructure layer, instead of being\nrebuilt inside every service.\nThe idea is for schemas, their governance, and now their meaning to finally\nlive in one place. So if you have data and you want to know what it means, you\nask Sourcemeta One."
newsletter: "Sourcemeta Newsletter"
newsletter_handle: "sourcemeta"
newsletter_url: "https://newsletter.sourcemeta.com/"
author: "Juan Cruz Viotti (@jviotti)"
published: "2026-07-14T00:00:00.000Z"
canonical_url: "https://newsletter.sourcemeta.com/a/fully-solving-json-schema-and-json-ld-interoperability"
markdown_url: "https://newsletter.sourcemeta.com/a/fully-solving-json-schema-and-json-ld-interoperability.md"
chat_url: "https://newsletter.sourcemeta.com/a/fully-solving-json-schema-and-json-ld-interoperability/chat"
source_url: "https://www.sourcemeta.com/blog/json-schema-jsonld-interoperability/"
body_source: "imported"
likes: 0
replies: 0
body_words: 4467
---

# Fully solving JSON Schema and JSON-LD interoperability

> TL;DR: The same [JSON Schema](https://json-schema.org) 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](https://www.w3.org/TR/json-ld11/) (the JSON serialisation of [RDF](https://www.w3.org/RDF/)). Annotate the schemas you already have, and every payload they validate becomes knowledge-graph-ready. Over the past decade, everyone from [MuleSoft](https://github.com/mulesoft-labs/json-ld-schema) to [Adobe](https://github.com/adobe/xdm/blob/master/docs/introduction.md) to [the Italian government](https://datatracker.ietf.org/doc/draft-polli-restapi-ld-keywords/) 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](https://github.com/sourcemeta/jsonschema/blob/main/docs/rdf.markdown) and in the [Sourcemeta One](https://one.sourcemeta.com/api/#rdf) registry.

There is a fair chance [JSON-LD](https://json-ld.org) lives in your head as “the [schema.org](https://schema.org) blob you paste into a web page so [Google shows rich results](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data)”. But [JSON-LD](https://www.w3.org/TR/json-ld11/) is much more than that. It is one of the credential formats the [EU Digital Identity Wallet](https://www.w3.org/TR/vc-data-model-2.0/) accepts, which all 27 member states must ship by December 2026. It is the foundation of Microsoft’s [Digital Twins Definition Language](https://learn.microsoft.com/en-us/azure/digital-twins/concepts-models). It is how [hundreds of thousands of machine-learning datasets](https://research.google/blog/croissant-a-metadata-format-for-ml-ready-datasets/) describe themselves on [Hugging Face](https://huggingface.co/docs/dataset-viewer/en/croissant) and [Kaggle](https://www.kaggle.com), how [all of EU law](https://op.europa.eu/en/web/eu-vocabularies/cellar) is published, and how websites [talk to AI agents](https://news.microsoft.com/source/features/company-news/introducing-nlweb-bringing-conversational-interfaces-directly-to-the-web/). [JSON-LD](https://json-ld.org) is what JSON looks like when it graduates into a [knowledge graph](https://cacm.acm.org/practice/industry-scale-knowledge-graphs/).

And yet, from where the [JSON Schema](https://json-schema.org) world sits, [JSON-LD](https://json-ld.org) 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](https://www.sourcemeta.com/blog/json-schema-dominates-openapi/)), [AsyncAPI](https://www.asyncapi.com/) message payloads, [MCP tool definitions](https://www.sourcemeta.com/blog/ai-only-speaks-json-schema/), [W3C Web of Things Thing Descriptions](https://json-schema.org/blog/posts/w3c-wot-case-study), the IETF’s [Semantic Definition Format](https://datatracker.ietf.org/doc/html/draft-ietf-asdf-sdf) for the Internet of Things, or plain standalone data models of the kind [governments now publish in national registries](https://www.sourcemeta.com/blog/g7-runs-on-json-schema/). *Sooner or later the same need appears: joining [JSON Schema](https://json-schema.org)’s validation strengths with [JSON-LD](https://json-ld.org)’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](https://json-schema.org) 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](https://datatracker.ietf.org/doc/draft-polli-restapi-ld-keywords/). Because the keywords are plain `x-` extensions rather than a formal [JSON Schema vocabulary](https://json-schema.org/draft/2020-12/json-schema-core#name-extending-json-schema), 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`](https://schema.org/Order) whose `seller` and `customer` reuse a single `party` definition through [`$ref`](https://www.learnjsonschema.com/2020-12/core/ref/), where a `party` reuses a shared `address`, and where a `party` is a [`schema.org/Person`](https://schema.org/Person) or a [`schema.org/Organization`](https://schema.org/Organization) depending on its `kind`.

```json
{
  "$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:

```json
{
  "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](https://github.com/sourcemeta/jsonschema):

```sh
$ jsonschema rdf schema.json instance.json
```

Both parties come out of the same [`$ref`](https://www.learnjsonschema.com/2020-12/core/ref/) with different [RDF](https://www.w3.org/RDF/) types, the seller an [`Organization`](https://schema.org/Organization) and the customer a [`Person`](https://schema.org/Person), each carrying an address typed as a [`schema.org/PostalAddress`](https://schema.org/PostalAddress) with its country promoted to the [EU country authority](http://publications.europa.eu/resource/authority/country/) IRI:

```json
[
  {
    "@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`](https://www.learnjsonschema.com/2020-12/core/ref/) exactly as validation does. One schema. One pass. If the instance is invalid, no [RDF](https://www.w3.org/RDF/) comes out at all. That output is in standard [JSON-LD expanded form](https://www.w3.org/TR/json-ld11/#expanded-document-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`:

```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:

```sh
$ jsonschema rdf schema.json instance.json --compact context.json
```

```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](https://json-ld.org), which is the JSON serialisation of [RDF](https://www.w3.org/RDF/), the [W3C](https://www.w3.org/RDF/)’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](https://en.wikipedia.org/wiki/Wikidata) holds 1.65 billion statements. [UniProt](https://sparql.uniprot.org/), the reference database of protein knowledge, exposes [over 190 billion triples](https://www.expasy.org/resources/uniprot-sparql-endpoint) through what is widely cited as the largest public [SPARQL](https://www.w3.org/TR/sparql11-query/) endpoint on earth, and the US [National Institutes of Health](https://pubchemdocs.ncbi.nlm.nih.gov/rdf) 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](https://lod-cloud.net/) and its [1,658 connected datasets](https://dl.acm.org/doi/full/10.1145/3786331). Governments are wired the same way: [every EU legal act is RDF](https://op.europa.eu/en/web/eu-vocabularies/cellar) behind a public endpoint, and [France’s statistics office](https://rdf.insee.fr/), its [national library](https://data.bnf.fr/en/semanticweb), and [Europeana’s](https://www.europeana.eu) 50 million cultural objects all publish in it. Healthcare does the same through [HL7 FHIR](https://www.hl7.org/fhir/rdf.html), 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](https://cacm.acm.org/practice/industry-scale-knowledge-graphs/). And it is how AI now gets its facts, since a model on its own is a [parametric memory that hallucinates](https://arxiv.org/html/2411.14258v1) and the fix is to ground it in a graph, the pattern behind [GraphRAG](https://arxiv.org/abs/2404.16130).

![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.](https://www.sourcemeta.com/blog/json-schema-jsonld-interoperability/victor-hugo.webp)

*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](https://data.bnf.fr/en/11907966/victor_hugo/).*

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](https://cacm.acm.org/practice/industry-scale-knowledge-graphs/) 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](https://en.wikipedia.org/wiki/Knowledge_Graph_%28Google%29) straight from it. The mechanism is [RDF](https://www.w3.org/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](https://arxiv.org/abs/2311.07509) measured a language model at 16% accuracy over a raw SQL database and 54% over the same data as a knowledge graph. [Gartner](https://www.gartner.com/en/newsroom/press-releases/2026-04-16-gartner-says-organizations-with-successful-ai-initiatives-invest-up-to-four-times-more-in-data-and-analytics-foundations) 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](https://www.globenewswire.com/news-release/2025/01/31/3018718/0/en/Knowledge-Graph-Research-Report-2025-Global-Market-to-Reach-6-93-Billion-by-2030-from-1-06-Billion-in-2024-Growing-at-a-CAGR-of-36-6-Changing-for-Organizations-Deal-with-Large-Data.html).

## 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](https://json-schema.org) owns structure, whether the container is [an OpenAPI specification](https://www.sourcemeta.com/blog/json-schema-dominates-openapi/), [an AI tool definition](https://www.sourcemeta.com/blog/ai-only-speaks-json-schema/), or [a national data registry](https://www.sourcemeta.com/blog/g7-runs-on-json-schema/). Then, [JSON-LD](https://json-ld.org) 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](https://json-schema.org) cannot say that `family_name` means [`schema.org/familyName`](https://schema.org/familyName), and a [JSON-LD](https://json-ld.org) 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.](https://www.sourcemeta.com/blog/json-schema-jsonld-interoperability/wot-thing-description.webp)

*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](https://www.w3.org/TR/wot-thing-description11/).*

Now picture closing that gap. For example, the [EU wallet schema](https://github.com/EWC-consortium/eudi-wallet-rulebooks-and-schemas) 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](https://www.w3.org/RDF/) world a powerful validation story, and it gives the [JSON Schema](https://json-schema.org) 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](https://www.commonwl.org) project named it in 2015, when it abandoned existing schema languages because [“none understand linked data”](https://github.com/common-workflow-language/schema_salad):

> “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](https://www.w3.org/TR/vc-data-model-2.0/)**: the standard beneath the EU wallet, carries a [JSON-LD](https://json-ld.org) `@context` for meaning and a separate [`credentialSchema`](https://www.w3.org/TR/vc-json-schema/) for structure in every single credential. It takes [a whole appendix](https://www.w3.org/TR/vc-data-model-2.0/#differences-between-contexts-types-and-credentialschemas) 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](https://www.w3.org/TR/vc-json-schema/#relationship-to-verifiable-credential-type-property): “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](https://github.com/openwallet-foundation/credo-ts), the OpenWallet Foundation’s wallet framework, ships the whole JSON-LD stack down to RDF canonicalisation and [nineteen hand-authored context documents](https://github.com/openwallet-foundation/credo-ts/blob/main/packages/core/src/modules/vc/jsonld/contexts/defaultContexts.ts), while `credentialSchema` is [modelled as an `id` and a `type`](https://github.com/openwallet-foundation/credo-ts/blob/main/packages/core/src/modules/vc/models/credential/W3cCredentialSchema.ts) that it never fetches or evaluates.
- **[WE BUILD](https://github.com/webuild-consortium)**: one of the EU-co-funded Large Scale Pilots now building that wallet, keeps its credential [JSON Schemas](https://github.com/webuild-consortium/webuild-attestation-rulebooks-catalog) in one repository owned by one working group, while [a second group](https://github.com/webuild-consortium/wp4-semantics-group) hand-maintains the [SKOS terminology, OWL vocabulary, and JSON-LD context](https://github.com/webuild-consortium/wp4-semantics-group/blob/main/vocab/README.md) 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](https://github.com/webuild-consortium/webuild-attestation-rulebooks-catalog/blob/main/rulebooks/rb-pid/README.md), under a column headed “Semantic Reference”, recording that `family_name` means [`w3id.org/ebwv#familyName`](https://w3id.org/ebwv#familyName) while [the schema next door](https://github.com/webuild-consortium/webuild-attestation-rulebooks-catalog/blob/main/data-schemas/sd-jwt/ds002-pid-sd-jwt.json) can only call it a string.
- **[GS1’s EPCIS](https://github.com/gs1/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](https://smart-data-models.github.io/data-models/)**: keep a schema for every entry in the catalogue, paired with a JSON-LD context.
- **[Gaia-X](https://docs.gaia-x.eu/technical-committee/architecture-document/22.10/self-description/)**: Europe’s flagship cloud-federation project, pairs a [JSON-LD](https://json-ld.org) self-description with a separate SHACL shape for every participant.
- **[Beckn](https://beckn.io)**: the open-commerce protocol from the architects of India’s Aadhaar and UPI, and the backbone of India’s government-backed [ONDC](https://ondc.org/about-ondc/) network and its [200 million transactions](https://cxotoday.com/press-release/ondc-surpasses-200-million-transactions-with-the-last-100mn-coming-in-just-6-months/), goes further still: it [normatively requires](https://github.com/beckn/protocol-specifications-v2/blob/main/docs/Schema_Design_Guide.md) every one of the [300+ concepts in its schema repository](https://github.com/beckn/schemas) to ship four artefacts side by side, an OpenAPI envelope, a JSON Schema, a JSON-LD context, and an RDF vocabulary.
- **[Adobe](https://github.com/adobe/xdm/blob/master/docs/introduction.md)**: specified its Experience Data Model in both grammars at once, then had to bolt on a [“Compatibility Mode”](https://experienceleague.adobe.com/en/docs/experience-platform/xdm/api/appendix) that flattens the [JSON-LD](https://json-ld.org) 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](https://github.com/json-schema-org/json-schema-vocabularies/issues/13). 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](https://datatracker.ietf.org/doc/draft-polli-restapi-ld-keywords/) 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](https://dl.acm.org/doi/10.1145/2872427.2883029). The meaning of a property can be split across files with [`$ref`](https://www.learnjsonschema.com/2020-12/core/ref/), combined through logical applicators like [`anyOf`](https://www.learnjsonschema.com/2020-12/applicator/anyof/), or made to depend on the data in complex ways through [`if`](https://www.learnjsonschema.com/2020-12/applicator/if/)/[`then`](https://www.learnjsonschema.com/2020-12/applicator/then/)/[`else`](https://www.learnjsonschema.com/2020-12/applicator/else/), and other similar keywords. With [`$dynamicRef`](https://www.learnjsonschema.com/2020-12/core/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](https://arxiv.org/abs/2307.10034). In comparison, a [JSON-LD](https://json-ld.org) 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`](https://schema.org/Person) or an [`Organization`](https://schema.org/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](https://json-ld.org) 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](https://www.w3.org/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](https://www.commonwl.org/draft-3/SchemaSalad.html) rebuilt the schema language on top of Avro, while [LinkML](https://linkml.io/linkml/generators/jsonld-context.html) and the automotive industry’s [Catena-X](https://catenax-ev.github.io/docs/next/standards/CX-0003-SAMMSemanticAspectMetaModel) generate JSON Schema from a separate RDF model you must author first. This path has real public-sector uptake: Switzerland’s [eCH](https://www.ech.ch/) 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](https://github.com/swiss/political-affairs-ech-group), 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](https://www.chiply.dev/post-schema-languages). “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](https://github.com/opengeospatial/ogc-na-tools) assembles the context from the schema at build time, and its own source carries a thirty-line comment about [“binding bubbling”](https://ogcincubator.github.io/bblocks-docs/create/semantic-uplift), where a referenced schema’s mappings silently overwrite the parent’s. India’s [Beckn](https://beckn.io) walks the same path today: its [generator scripts](https://github.com/beckn/schemas/tree/main/tools) scrape property names out of a schema and map each one to a flat `beckn:` IRI, blind to [`$ref`](https://www.learnjsonschema.com/2020-12/core/ref/) (in one [typical concept](https://github.com/beckn/schemas/tree/main/schema/AckNoCallback/v2.0), 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`](https://github.com/transmute-industries/verifiable-data/blob/main/packages/jsonld-schema/src/schemasToContext.ts), from [Transmute](https://transmute.industries), which holds an editor’s seat on [the VC JSON Schema specification](https://www.w3.org/TR/vc-json-schema/), 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](https://github.com/hashgraph/guardian) vendors the file itself, and the [W3C CCG traceability vocabulary](https://github.com/w3c-ccg/traceability-vocab/blob/main/packages/traceability-schemas/scripts/openapi-to-context.js) builds its context from its own copy of the same design. Each reads a single level of `properties` and resolves no [`$ref`](https://www.learnjsonschema.com/2020-12/core/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](https://github.com/mulesoft-labs/json-ld-schema) validated existing JSON-LD with JSON Schema before being archived at “pre-alpha”, and [RML](https://rml.io/specs/rml/) and the AI-assisted [MetaConfigurator](https://arxiv.org/abs/2606.07094) add a third artefact to drift from the other two. Even [Adobe](https://github.com/adobe/xdm/blob/master/docs/introduction.md) and [Autodesk](https://www.research.autodesk.com/app/uploads/2023/03/TranslatingJSONSchemalogicsintoOWLaxioms.pdf_recQnFKTPMiScRn8N.pdf) 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.](https://www.sourcemeta.com/blog/json-schema-jsonld-interoperability/ogc-context-assembly.webp)

*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](https://ogcincubator.github.io/bblocks-docs/create/semantic-uplift).*

## 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](https://github.com/italia/daf-ontologie-vocabolari-controllati) that models its public administration as a knowledge graph, and a [national platform of services](https://www.sourcemeta.com/blog/g7-runs-on-json-schema/) 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.](https://www.sourcemeta.com/blog/json-schema-jsonld-interoperability/italy-cpv-person-ontology.webp)

*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](https://schema.gov.it/lode/extract?url=https://w3id.org/italia/onto/CPV).*

Even so, [Roberto Polli’s REST API Linked Data Keywords IETF proposal for this problem](https://datatracker.ietf.org/doc/draft-polli-restapi-ld-keywords/) (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](https://github.com/transmute-industries/verifiable-data/blob/main/packages/jsonld-schema/src/schemasToContext.ts) (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`](https://www.learnjsonschema.com/2020-12/core/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](https://github.com/beckn/schemas) (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](https://www.w3.org/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](https://github.com/sourcemeta/blaze), a high-performance C++ [JSON Schema validator](https://www.vldb.org/pvldb/vol19/p279-viotti.pdf) 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](https://json-ld.org) engine that rides along, producing the [RDF](https://www.w3.org/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](https://github.com/sourcemeta/jsonschema/blob/main/docs/rdf.markdown) 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`](https://github.com/sourcemeta/jsonschema/blob/main/docs/rdf.markdown) at a schema and an instance, and get [JSON-LD](https://json-ld.org) 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](https://www.sourcemeta.com/blog/json-schema-jsonld-interoperability/annotation-vocabulary.webp)

*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](https://github.com/sourcemeta/jsonschema/blob/main/docs/rdf.markdown)*

But the command line is the small version of the idea. The same engine ships in [Sourcemeta One](https://one.sourcemeta.com/api/#rdf), our flagship schema registry, where it runs over HTTP. Every schema the registry governs can turn an instance into [JSON-LD](https://json-ld.org) 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.

***

## Discussion

No replies yet.
