Practical Implementation

What is `@context`?

The @context provides a semantic reference framework that defines how the fields in the credential should be interpreted. This ensures that any system processing the credential correctly understands the terms used, such as name, surname, and other attributes.

There are two main ways to include @context in a credential:

By linking to an external file: This file defines how the fields of the credential should be interpreted.
By directly including the terms in the @context field within the credential itself.

Both methods are valid, and the choice depends on whether you prefer modularity or simplicity in your implementation.

Practical Example: University Professor Credential

Here is an example of a verifiable credential for a university professor using @context. In this example, @context is included via an external link:

{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://w3id.org/security/bbs/v1", "https://contextvc.blob.core.windows.net/v100/betrusty.json" ], "id": "http://example.edu/credentials/1872345768965", "type": ["VerifiableCredential", "CitizenCard"], "issuer": "did:quarkid:EiBwuES6qXXTOq58VZVQD4zakSktrIm6IC1zY825bnAHsg", "issuanceDate": "2024-08-24", "credentialSubject": { "Nombre": "Javier", "Apellido": "Magdalena", "Trabajo": "Profesor", "Pais": "Argentina" } }

How does `@context` work?

In this example, the @context field includes three links:

https://www.w3.org/2018/credentials/v1: Defines general terms for verifiable credentials following the W3C standard.
https://w3id.org/security/bbs/v1: Defines terms for cryptographic signatures.
https://contextvc.blob.core.windows.net/v100/betrusty.json: Defines specific terms for the credential, such as Nombre, Apellido, Trabajo, and Pais.

The JSON-LD file linked in betrusty.json would look like this:

{ "@context": { "Nombre": "https://schema.org/text", "Apellido": "https://schema.org/text", "Trabajo": "https://schema.org/text", "Pais": "https://schema.org/text" } }

Practical Example: University Student Credential

Now let’s see another case, a verifiable credential for a university student. Here, we include the @context directly in the credential:

{ "@context": [ "https://www.w3.org/2018/credentials/v1", { "Nombre": "https://schema.org/text", "Apellido": "https://schema.org/text", "Matricula": "https://schema.org/text", "Institucion": "https://schema.org/text", "Carrera": "https://schema.org/text", "Pais": "https://schema.org/text" } ], "id": "http://example.edu/credentials/192837465", "type": ["VerifiableCredential", "StudentID"], "issuer": "did:quarkid:EiBwuES6qXXTOq58VZVQD4zakSktrIm6IC1zY825bnAHsg", "issuanceDate": "2024-08-24", "credentialSubject": { "Nombre": "Ana", "Apellido": "López", "Matricula": "123456789", "Institucion": "Universidad Ejemplo", "Carrera": "Ingenieria", "Pais": "Mexico" } }

In this case:

Fields like Nombre, Apellido, Matricula, Institucion, Carrera, and Pais are defined directly in the @context instead of using an external link.

Considerations for Using Accents and Special Characters

It’s important to note that some systems do not properly recognize accents or special characters, which can cause errors when verifying credentials. For example, if a field like “País” contains an accent, some systems might not process it correctly. To avoid these issues, it’s recommended not to use accents or special characters in the names of fields in @context or in the terms of the credential when using languages like Spanish.

Instead of writing “País”, use “Pais”, and instead of “Matrícula”, use “Matricula”. This ensures that credentials will work correctly in any system that processes JSON-LD.

Improvement for Ensuring True Interoperability

While the previous examples use https://schema.org/text for all fields, the ideal approach for ensuring true interoperability is to use more specific terms from schema.org that best fit the data you’re handling. This not only ensures that data is correctly understood but also enhances interoperability across different systems.

A more appropriate approach would be to look for terms in schema.org that are better defined for the types of data you’re handling. Here’s how a credential would look using more specific terms from schema.org:

{"@context": [ "https://www.w3.org/2018/credentials/v1", { "givenName": "https://schema.org/givenName", "familyName": "https://schema.org/familyName", "identifier": "https://schema.org/identifier", "educationalOrganization": "https://schema.org/EducationalOrganization", "educationalCredentialAwarded": "https://schema.org/educationalCredentialAwarded", "addressCountry": "https://schema.org/addressCountry" } ], "id": "http://example.edu/credentials/192837465", "type": ["VerifiableCredential", "StudentID"], "issuer": "did:quarkid:EiBwuES6qXXTOq58VZVQD4zakSktrIm6IC1zY825bnAHsg", "issuanceDate": "2024-08-24", "credentialSubject": { "givenName": "Ana", "familyName": "Lopez", "identifier": "123456789", "educationalOrganization": "Universidad Ejemplo", "educationalCredentialAwarded": "Ingenieria", "addressCountry": "Mexico" } }

In this case:

We use terms such as givenName for the first name, familyName for the last name, and other specific terms that better fit the data types being used, thus improving interoperability.

Summary

The @context defines how data in a verifiable credential is interpreted, allowing systems that follow W3C and DIF standards to process the information coherently.
You can use an external file or directly include the terms in the credential.
Avoid using accents or special characters in the field names, as they can cause issues in some systems (Note: this issue is specific to languages like Spanish, and it won’t affect English field names).
To ensure optimal interoperability, use specific terms from schema.org that best fit the data types you need to represent.