JSON-LD: JavaScript Object Notation for Linked Data

Definition

How JSON-LD Works: Contexts and Semantics

At the heart of JSON-LD is the concept of a context, specified using the @context keyword. A context document maps short, human-readable property names (like "name" or "dateOfBirth") to full Internationalized Resource Identifiers (IRIs) that provide precise, globally unique definitions. This mapping ensures that when two different systems process the same credential, they interpret each field identically.

For example, a credential might include "@context": ["https://www.w3.org/2018/credentials/v1", "https://example.eu/identity/v1"]. The first context defines standard verifiable credential properties (issuer, holder, proof), while the second defines domain-specific properties (nationalId, drivingPrivileges). This layered context approach allows credentials to combine standard and specialized vocabularies.

JSON-LD also supports type coercion (automatically converting values to specific data types), language tagging (associating text with specific languages), and graph relationships (linking entities to each other). These features enable rich, multilingual credential representations -- important for an EU-wide identity system operating across 24 official languages.

The @type keyword allows credentials to declare their type, such as "VerifiableCredential", "EuropeanDriverLicense", or "UniversityDegreeCredential". Verifiers can use this type information to determine which processing rules and validation schemas to apply, enabling automated credential handling at scale.

Role in the W3C Verifiable Credentials Ecosystem

JSON-LD is a foundational technology in the W3C Verifiable Credentials Data Model. The VC specification requires that every verifiable credential includes an @context property, even when using the JWT or SD-JWT encoding. This ensures that all credentials carry their semantic definitions, regardless of the serialization format used.

In the original W3C VC Data Model 1.1, JSON-LD processing was mandatory -- verifiers had to resolve context documents and perform JSON-LD expansion before validating credentials. The updated VC Data Model 2.0 relaxed this requirement, allowing implementations to treat JSON-LD contexts as simple documentation without full processing, which aligns better with the EUDI Wallet approach of using SD-JWT as a primary format.

For the EUDI Wallet ecosystem specifically, the EU is defining standardized credential schemas and JSON-LD contexts for common credential types: Person Identification Data (PID), mobile driving licenses, educational credentials, professional qualifications, and health certificates. These EU-defined contexts ensure that a diploma credential issued by a Spanish university can be correctly interpreted by a German employer using a different EUDI Wallet implementation.

JSON-LD vs. JSON Schema in EUDI Wallets

While JSON-LD and JSON Schema both describe the structure of JSON documents, they serve different purposes. JSON-LD provides semantic meaning (what each field represents), while JSON Schema provides structural validation (what data types and patterns are allowed). In practice, EUDI Wallet credentials often use both: JSON-LD contexts for semantic interoperability and JSON Schema for validation.

For example, a Person Identification Data (PID) credential might have a JSON-LD context that maps "family_name" to a specific schema.org property, and a JSON Schema that specifies family_name must be a string with maximum length of 150 characters. The JSON-LD context ensures the field is correctly interpreted, while the JSON Schema ensures the data format is valid.

This dual approach provides both machine-readability through JSON-LD semantics and practical data validation through JSON Schema constraints, creating a strong foundation for cross-border credential exchange within the EUDI Wallet ecosystem.

Related Terms