JSON-LD explained
JSON-LD is ordinary JSON with one extra line that says what the fields mean. That line turns a local field name into a globally defined one, so a system that has never seen your data can still work out what you are talking about. It has been a W3C standard since 2014, it is how search engines read this very page, and it is what the W3C verifiable credentials data model is built on.
The problem with plain JSON
JSON says how data is written down. It says nothing about what any of it means. A field called name could be a person, a company or a product. A field called id could be a customer number, a passport number or a row in somebody’s database. Two systems can both emit perfectly valid JSON and still disagree about every field in it.
In practice that gap gets closed by an agreement. The two parties write down what the fields mean and build their software to match. That works for one integration, gets expensive at ten, and stops working altogether when a credential issued in one country has to be understood by a verifier in another that nobody spoke to in advance.
What the @context does
JSON-LD closes that gap inside the document itself. A @context maps each short field name onto a globally unique identifier, normally a URL controlled by whoever defined the vocabulary. The field stays short and readable for a human and becomes unambiguous for a machine.
Plain JSON
{
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Valid, readable and meaningless to anyone who was not told in advance what the fields are supposed to hold.
The same data as JSON-LD
{
"@context": "https://schema.org",
"@type": "Person",
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Every field now points at a published definition, so a system that has never seen this document can still read it correctly.
- @context names the vocabulary that every field in the document is defined in.
- @type says what kind of thing the document describes, so the right definitions are picked from that vocabulary.
Nothing about the data itself changes. The same values in the same shape now carry a pointer to the definition of every field. A receiving system that recognises the vocabulary knows exactly what it was handed, and one that does not can still read the document as ordinary JSON and ignore the rest.
That is the whole idea. Meaning travels with the document instead of living in a specification the two parties had to agree on beforehand.
Where it shows up in verifiable credentials
The W3C Verifiable Credentials Data Model 2.0, a W3C Recommendation since 15 May 2025, is built on JSON-LD. Every credential opens with a @context whose first value is the shared credentials vocabulary, so the terms that every credential has in common, the issuer, the subject, the validity dates and the status information, mean the same thing everywhere.
Anything beyond that comes from a second vocabulary. A university publishes one for diploma fields, a chamber of commerce one for company registration fields. A verifier that cares about diplomas loads the first, a verifier that cares about company data loads the second, and neither has to be changed when the other adds a field.
That is what lets one credential format carry data nobody anticipated when the format was written, which is the property an open ecosystem needs and a closed profile does not.
Signing linked data
A credential also has to be signed, and the data model deliberately leaves a choice there. An enveloping proof wraps the whole credential in a signature container such as a JWT. The bytes are signed exactly as they are, so anything that reorders or reformats them on the way breaks the signature.
An embedded Data Integrity proof works the other way round. The document is first put into a canonical form, defined by RDF Dataset Canonicalization and a W3C Recommendation since 21 May 2024, and the signature covers that form rather than the bytes. Because the canonical form does not depend on key order, whitespace or which short names the @context happens to use, the signature survives being written out again somewhere else.
Where it fits in the EUDI Wallet
Not where most people assume. The Architecture and Reference Framework names two credential formats for the European wallet, SD-JWT VC and mdoc, and neither of them is JSON-LD. An organisation issuing into the EUDI Wallet today will not meet a @context on the way.
The reasoning is implementability. Both formats have a fixed shape, one signature mechanism and no document a verifier has to go and fetch before it can check anything. For a wallet running on a phone and a verifier that has to answer in milliseconds, that is worth more than an open vocabulary.
JSON-LD earns its place where data has to travel beyond the ecosystem that defined it: product passports and supply chain data, cross sector pilots, and credential types no central profile is ever going to enumerate. The two worlds overlap more often than they compete, and organisations working across both usually end up supporting both.
The other JSON-LD, the one you have already used
Long before credentials, JSON-LD became the way a website tells a search engine what a page is about. A block of it in the page source, using the schema.org vocabulary, is what turns a page into a recognised article, product, event or organisation. This page carries one.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "JSON-LD explained",
"description": "What JSON-LD adds to plain JSON, how a @context gives every field one meaning, and where verifiable credentials use it.",
"image": "https://www.credenco.com/images/og-default.jpg",
"datePublished": "2026-10-15",
"dateModified": "2026-10-15",
"inLanguage": "en",
"mainEntityOfPage": "https://www.credenco.com/explained/json-ld",
"author": {
"@type": "Organization",
"name": "Credenco",
"url": "https://www.credenco.com/"
},
"publisher": {
"@type": "Organization",
"name": "Credenco",
"logo": {
"@type": "ImageObject",
"url": "https://www.credenco.com/logo.svg"
}
}
}It is the same format with a different vocabulary, and it is the clearest way to see the point. Nobody here agreed anything with any search engine. The @context points at schema.org, the search engine already knows that vocabulary, and the page is understood by a party it never spoke to. A credential crossing a border does exactly the same thing.
What it costs you
The context has to be available. A verifier that fetches it at verification time has added a network dependency to a security decision, and whoever serves that document can change what the credential appears to say. Real deployments pin the contexts they accept and ship them with the software instead of resolving them live.
Canonicalization is real work too. Turning a document into a canonical dataset before signing is considerably more code than signing bytes, and its failure modes are subtle. The documents are larger as well, which starts to matter on a QR code or an NFC tap.
None of that makes JSON-LD the wrong choice. It makes it a choice: pay for open vocabularies where data has to outlive the agreement that created it, and skip them where a fixed profile already says everything the two parties need.
What this means for you
Issuer
Issuing into the EUDI Wallet means SD-JWT VC or mdoc, and JSON-LD never comes up. Issuing into a W3C ecosystem makes your @context a long term commitment: it is the public definition of your fields, and changing it breaks every verifier that cached the old one.
Verifier
Decide which contexts you accept and ship them with your software. Fetching one during verification makes a remote server part of your security decision and puts a network call in the middle of your response time.
Developer
Read a JSON-LD document as ordinary JSON when all you need is a field, and reach for a full processor only where you actually expand or canonicalize. Most of the complexity people attribute to JSON-LD sits in the signing path, not the parsing path.
Related terms
Frequently asked questions
Is JSON-LD still just JSON?
Yes. Every JSON-LD document is valid JSON, and software that only needs to read a field can treat it as such. The extra machinery comes into play when you expand a document into its full form or canonicalize it for signing, which most code reading a credential never does.
Does the EUDI Wallet use JSON-LD?
No. The Architecture and Reference Framework names SD-JWT VC and mdoc as the credential formats, and neither of them uses JSON-LD. It matters for W3C verifiable credential ecosystems, product passports and supply chain data rather than for the European wallet itself.
Does a verifier download the @context every time?
It should not. Fetching a context during verification puts a network call inside a security decision and hands a remote server the ability to change what the document appears to say. Implementations pin the contexts they accept and ship them with the software, which removes the latency as well.
Is this the same JSON-LD that search engines read?
The same format with a different vocabulary. Structured data on a web page points its @context at schema.org, while a credential points it at the credentials vocabulary and whatever else it needs. The processing rules are identical in both cases.
Sources
This page is informational and does not constitute legal advice. For authoritative guidance consult the W3C specifications directly.