Implementación práctica

¿Qué es el `@context`?

El @context proporciona un marco de referencia semántico que define cómo deben interpretarse los campos de la credencial. Esto asegura que cualquier sistema que procese la credencial entienda correctamente los términos utilizados, como el nombre, apellido, y otros atributos.

Beneficios del uso de `@context`:

Interoperabilidad: Garantiza que las credenciales sean entendidas por cualquier sistema que siga los estándares W3C y DIF.
Modularidad: Usar enlaces externos te permite actualizar el contexto sin modificar las credenciales emitidas.
Flexibilidad: Incluir los términos directamente en la credencial es útil para implementaciones más simples.
Prevención de errores: Evitar el uso de caracteres especiales como tildes asegura que las credenciales funcionen en cualquier plataforma.

Existen dos formas principales de incluir el @context en una credencial:

A través de un enlace a un archivo externo: Este archivo define cómo deben interpretarse los campos de la credencial.
Incluyendo directamente los términos en el campo @context dentro de la propia credencial.

Ambos métodos son válidos, y la elección depende de si prefieres modularidad o simplicidad en tu implementación.

Ejemplo práctico: Credencial de profesor universitario

Aquí te mostramos un ejemplo de una credencial verificable de profesor universitario utilizando el @context. A lo largo de esta explicación nos basaremos en este código.

En este ejemplo, el @context se incluye mediante un enlace externo:

{"@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" } }

¿Cómo funciona el `@context`?

En este ejemplo, el campo @context incluye tres enlaces:

https://www.w3.org/2018/credentials/v1: Define los términos generales para las credenciales verificables siguiendo el estándar W3C.
https://w3id.org/security/bbs/v1: Define términos para firmas criptográficas.
https://contextvc.blob.core.windows.net/v100/betrusty.json: Define los términos específicos de la credencial, como Nombre, Apellido, Trabajo y Pais.

El archivo JSON-LD vinculado en betrusty.json se vería así:

{

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

Ahora veamos otro caso, una credencial verificable para un estudiante universitario. Aquí incluimos el @context directamente en la credencial:

{

"@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": "Lopez", "Matricula": "123456789", "Institucion": "Universidad Ejemplo", "Carrera": "Ingenieria", "Pais": "Mexico" } }

En este caso:

Se han definido términos como Nombre, Apellido, Matricula, Institucion, Carrera, y Pais directamente en el @context en lugar de usar un enlace externo.

Ejemplo práctico: Credencial de Estudiante Universitario

Ahora veamos otro caso, una credencial verificable para un estudiante universitario. Aquí incluimos el @context directamente en la credencial:

{"@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": "Lopez", "Matricula": "123456789", "Institucion": "Universidad Ejemplo", "Carrera": "Ingenieria", "Pais": "Mexico" } }

En este caso:

Se han definido términos como Nombre, Apellido, Matricula, Institucion, Carrera, y Pais directamente en el @context en lugar de usar un enlace externo.

Consideraciones sobre el uso de tildes y caracteres especiales

Es importante tener en cuenta que algunos sistemas no reconocen correctamente las tildes o caracteres especiales, lo que puede generar errores en la verificación de las credenciales. Por ejemplo, si un campo como “País” contiene una tilde, algunos sistemas pueden no procesarlo correctamente. Para evitar estos problemas, se recomienda no usar tildes o caracteres especiales en los nombres de los campos en el @context ni en los términos de la credencial.

En lugar de escribir “País”, usa “Pais”, y en lugar de “Matrícula”, usa “Matricula”. Esto garantizará que las credenciales funcionen correctamente en cualquier sistema que procese JSON-LD.

Mejora para garantizar una verdadera interoperabilidad

Es importante destacar que, aunque en los ejemplos anteriores hemos utilizado https://schema.org/text para todos los campos, lo ideal sería utilizar términos más específicos de schema.org que mejor se adapten a los datos que estamos manejando. Esto no solo asegura que los datos sean comprendidos correctamente, sino que también mejora la interoperabilidad entre diferentes sistemas.

Un enfoque más correcto sería buscar términos de schema.org que estén más definidos para los tipos de datos que estamos utilizando. Aquí te mostramos cómo se vería una credencial utilizando términos más específicos de 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" } }

En este caso:

Se han utilizado términos como givenName para el nombre, familyName para el apellido, y otros términos más específicos que se ajustan a los tipos de datos que estamos utilizando, mejorando así la interoperabilidad.

Resumen

El @context define cómo se interpretan los datos en una credencial verificable, permitiendo que sistemas que siguen los estándares W3C y DIF puedan procesar la información de manera coherente.
Puedes usar un archivo externo o incluir directamente los términos en la credencial.
Evita el uso de tildes o caracteres especiales en los nombres de los campos, ya que pueden causar problemas en algunos sistemas.
Para garantizar una interoperabilidad óptima, utiliza términos específicos de schema.org que mejor se adapten a los tipos de datos que necesitas representar.