JSON-LD explicado
JSON-LD es JSON corriente con una línea adicional que dice qué significan los campos. Esa línea convierte un nombre de campo local en uno definido globalmente, de modo que un sistema que nunca ha visto sus datos puede deducir de qué está hablando. Es un estándar del W3C desde 2014, es la forma en que los motores de búsqueda leen esta misma página, y es la base del modelo de datos del W3C para credenciales verificables.
El problema del JSON corriente
JSON dice cómo se escriben los datos. No dice nada sobre qué significa cada cosa. Un campo llamado name puede ser una persona, una empresa o un producto. Un campo llamado id puede ser un número de cliente, un número de pasaporte o una fila en la base de datos de alguien. Dos sistemas pueden emitir ambos JSON perfectamente válido y aun así discrepar sobre cada campo.
En la práctica, esa brecha se cierra con un acuerdo. Las dos partes dejan por escrito qué significan los campos y construyen su software en consecuencia. Eso funciona para una integración, se vuelve caro con diez y deja de funcionar por completo cuando una credencial emitida en un país tiene que ser entendida por un verificador de otro con el que nadie habló de antemano.
Qué hace el @context
JSON-LD cierra esa brecha dentro del propio documento. Un @context asigna a cada nombre de campo abreviado un identificador único a escala mundial, normalmente una URL controlada por quien definió el vocabulario. El campo sigue siendo corto y legible para una persona y se vuelve inequívoco para una máquina.
JSON corriente
{
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Válido, legible y carente de significado para cualquiera a quien nadie haya dicho de antemano qué se supone que contienen los campos.
Los mismos datos como JSON-LD
{
"@context": "https://schema.org",
"@type": "Person",
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Cada campo apunta ahora a una definición publicada, de modo que un sistema que nunca ha visto este documento puede leerlo correctamente igualmente.
- @context nombra el vocabulario en el que está definido cada campo del documento.
- @type indica qué tipo de cosa describe el documento, para que se tomen las definiciones correctas de ese vocabulario.
Nada cambia en los datos en sí. Los mismos valores, con la misma forma, llevan ahora un puntero a la definición de cada campo. Un sistema receptor que reconoce el vocabulario sabe exactamente qué le han entregado, y uno que no lo reconoce puede seguir leyendo el documento como JSON corriente e ignorar el resto.
Esa es toda la idea. El significado viaja con el documento en lugar de residir en una especificación que las dos partes tenían que acordar de antemano.
Dónde aparece en las credenciales verificables
El W3C Verifiable Credentials Data Model 2.0, W3C Recommendation desde el 15 de mayo de 2025, está construido sobre JSON-LD. Cada credencial empieza con un @context cuyo primer valor es el vocabulario compartido de credenciales, de modo que los términos que toda credencial tiene en común, el emisor, el sujeto, las fechas de validez y la información de estado, significan lo mismo en todas partes.
Todo lo demás procede de un segundo vocabulario. Una universidad publica uno para los campos de los títulos, una cámara de comercio otro para los campos de registro mercantil. Un verificador al que le interesan los títulos carga el primero, uno al que le interesan los datos de empresa carga el segundo, y ninguno de los dos tiene que cambiar cuando el otro añade un campo.
Eso es lo que permite que un mismo formato de credencial lleve datos que nadie previó cuando se escribió el formato, que es la propiedad que un ecosistema abierto necesita y un perfil cerrado no.
Firmar datos enlazados
Una credencial también hay que firmarla, y el modelo de datos deja ahí una elección de forma deliberada. Una prueba envolvente empaqueta toda la credencial en un contenedor de firma como un JWT. Los bytes se firman exactamente tal y como están, así que cualquier cosa que los reordene o los reformatee por el camino rompe la firma.
Una prueba Data Integrity incrustada funciona al revés. El documento se lleva primero a una forma canónica, definida por RDF Dataset Canonicalization y W3C Recommendation desde el 21 de mayo de 2024, y la firma cubre esa forma en lugar de los bytes. Como la forma canónica no depende del orden de las claves, de los espacios ni de qué nombres cortos use el @context, la firma sobrevive a que el documento se vuelva a escribir en otro sitio.
Su lugar en la EUDI Wallet
No donde la mayoría supone. El Architecture and Reference Framework señala dos formatos de credencial para la cartera europea, SD-JWT VC y mdoc, y ninguno de los dos es JSON-LD. Una organización que emita hoy hacia la EUDI Wallet no se encontrará ningún @context por el camino.
El razonamiento es la facilidad de implementación. Ambos formatos tienen una estructura fija, un único mecanismo de firma y ningún documento que un verificador tenga que ir a buscar antes de poder comprobar nada. Para una cartera que funciona en un teléfono y un verificador que debe responder en milisegundos, eso vale más que un vocabulario abierto.
JSON-LD se gana su sitio allí donde los datos tienen que viajar más allá del ecosistema que los definió: pasaportes de producto y datos de la cadena de suministro, pilotos intersectoriales y tipos de credencial que ningún perfil central va a enumerar nunca. Los dos mundos se solapan más a menudo de lo que compiten, y las organizaciones que trabajan en ambos acaban normalmente admitiendo los dos.
El otro JSON-LD, el que ya ha usado
Mucho antes de las credenciales, JSON-LD se convirtió en la manera en que un sitio web le dice a un motor de búsqueda de qué trata una página. Un bloque de JSON-LD en el código fuente de la página, con el vocabulario de schema.org, es lo que convierte una página en un artículo, producto, evento u organización reconocidos. Esta página lleva uno.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "JSON-LD explicado",
"description": "Qué añade JSON-LD al JSON corriente, cómo un @context da un único significado a cada campo y dónde lo usan las credenciales verificables.",
"image": "https://www.credenco.com/images/og-default.jpg",
"datePublished": "2026-10-15",
"dateModified": "2026-10-15",
"inLanguage": "es",
"mainEntityOfPage": "https://www.credenco.com/es/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"
}
}
}Es el mismo formato con un vocabulario distinto, y es la forma más clara de ver la idea. Nadie aquí ha acordado nada con ningún motor de búsqueda. El @context apunta a schema.org, el motor de búsqueda ya conoce ese vocabulario, y la página la entiende una parte con la que nunca ha hablado. Una credencial que cruza una frontera hace exactamente lo mismo.
Lo que cuesta
El contexto tiene que estar disponible. Un verificador que lo obtiene en el momento de la verificación ha añadido una dependencia de red a una decisión de seguridad, y quien sirva ese documento puede cambiar lo que la credencial parece decir. Los despliegues reales fijan los contextos que aceptan y los distribuyen con el software en lugar de resolverlos en vivo.
La canonización también es trabajo real. Convertir un documento en un conjunto de datos canónico antes de firmarlo es bastante más código que firmar bytes, y sus modos de fallo son sutiles. Además los documentos son más grandes, lo que empieza a importar en un código QR o en un toque NFC.
Nada de eso convierte a JSON-LD en la elección equivocada. Lo convierte en una elección: pague por vocabularios abiertos allí donde los datos tienen que sobrevivir al acuerdo que los creó, y prescinda de ellos donde un perfil fijo ya dice todo lo que las dos partes necesitan.
Qué significa esto para usted
Emisor
Emitir hacia la EUDI Wallet significa SD-JWT VC o mdoc, y JSON-LD no aparece nunca. Emitir hacia un ecosistema W3C convierte su @context en un compromiso a largo plazo: es la definición pública de sus campos, y cambiarlo rompe todo verificador que haya guardado en caché la versión anterior.
Verificador
Decida qué contextos acepta y distribúyalos con su software. Obtener uno durante la verificación convierte a un servidor remoto en parte de su decisión de seguridad y coloca una llamada de red en mitad de su tiempo de respuesta.
Desarrollador
Lea un documento JSON-LD como JSON corriente cuando solo necesite un campo, y recurra a un procesador completo solo donde realmente expanda o canonice. La mayor parte de la complejidad que se atribuye a JSON-LD está en el camino de la firma, no en el de la lectura.
Términos relacionados
Preguntas frecuentes
¿JSON-LD sigue siendo simplemente JSON?
Sí. Todo documento JSON-LD es JSON válido, y un software que solo necesita leer un campo puede tratarlo como tal. La maquinaria adicional entra en juego cuando se expande un documento a su forma completa o se canoniza para firmarlo, algo que la mayor parte del código que lee una credencial nunca hace.
¿La EUDI Wallet usa JSON-LD?
No. El Architecture and Reference Framework señala SD-JWT VC y mdoc como formatos de credencial, y ninguno de los dos usa JSON-LD. Importa para los ecosistemas W3C de credenciales verificables, los pasaportes de producto y los datos de la cadena de suministro, no para la cartera europea en sí.
¿Un verificador descarga el @context cada vez?
No debería. Obtener un contexto durante la verificación coloca una llamada de red dentro de una decisión de seguridad y da a un servidor remoto la capacidad de cambiar lo que el documento parece decir. Las implementaciones fijan los contextos que aceptan y los distribuyen con el software, lo que además elimina la latencia.
¿Es el mismo JSON-LD que leen los motores de búsqueda?
El mismo formato con un vocabulario distinto. Los datos estructurados de una página web apuntan su @context a schema.org, mientras que una credencial lo apunta al vocabulario de credenciales y a lo demás que necesite. Las reglas de procesamiento son idénticas en ambos casos.
Fuentes
Esta página es informativa y no constituye asesoramiento jurídico. Para una orientación autorizada, consulte directamente las especificaciones del W3C.