JSON-LD explicado
O JSON-LD é JSON comum com uma linha adicional que diz o que os campos significam. Essa linha transforma um nome de campo local num nome definido globalmente, pelo que um sistema que nunca viu os seus dados consegue ainda assim perceber do que está a falar. É uma norma do W3C desde 2014, é assim que os motores de busca leem esta mesma página e é a base do modelo de dados do W3C para credenciais verificáveis.
O problema do JSON simples
O JSON diz como os dados são escritos. Não diz nada sobre o que significam. Um campo chamado name pode ser uma pessoa, uma empresa ou um produto. Um campo chamado id pode ser um número de cliente, um número de passaporte ou uma linha na base de dados de alguém. Dois sistemas podem ambos produzir JSON perfeitamente válido e ainda assim discordar sobre cada campo.
Na prática, essa lacuna é fechada por um acordo. As duas partes registam o que os campos significam e constroem o software em conformidade. Isso funciona para uma integração, fica caro com dez e deixa de funcionar por completo quando uma credencial emitida num país tem de ser entendida por um verificador de outro com quem ninguém falou de antemão.
O que o @context faz
O JSON-LD fecha essa lacuna dentro do próprio documento. Um @context associa cada nome de campo abreviado a um identificador único a nível mundial, normalmente um URL controlado por quem definiu o vocabulário. O campo mantém-se curto e legível para uma pessoa e torna-se inequívoco para uma máquina.
JSON simples
{
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Válido, legível e sem significado para quem não foi informado previamente do que os campos devem conter.
Os mesmos dados em JSON-LD
{
"@context": "https://schema.org",
"@type": "Person",
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Cada campo aponta agora para uma definição publicada, pelo que um sistema que nunca viu este documento consegue mesmo assim lê-lo corretamente.
- @context nomeia o vocabulário em que cada campo do documento está definido.
- @type diz que tipo de coisa o documento descreve, para que sejam escolhidas as definições certas desse vocabulário.
Nada muda nos dados em si. Os mesmos valores, na mesma forma, passam a trazer um apontador para a definição de cada campo. Um sistema recetor que reconhece o vocabulário sabe exatamente o que lhe foi entregue, e um que não o reconhece continua a poder ler o documento como JSON comum e ignorar o resto.
A ideia é toda esta. O significado viaja com o documento em vez de residir numa especificação sobre a qual as duas partes tinham de chegar a acordo previamente.
Onde surge nas credenciais verificáveis
O W3C Verifiable Credentials Data Model 2.0, W3C Recommendation desde 15 de maio de 2025, assenta em JSON-LD. Cada credencial abre com um @context cujo primeiro valor é o vocabulário partilhado de credenciais, pelo que os termos que todas as credenciais têm em comum, o emissor, o sujeito, as datas de validade e a informação de estado, significam o mesmo em toda a parte.
Tudo o resto vem de um segundo vocabulário. Uma universidade publica um para os campos dos diplomas, uma câmara de comércio outro para os campos do registo comercial. Um verificador interessado em diplomas carrega o primeiro, um verificador interessado em dados de empresa carrega o segundo, e nenhum dos dois tem de mudar quando o outro acrescenta um campo.
É isto que permite a um único formato de credencial transportar dados que ninguém previu quando o formato foi escrito, e essa é a propriedade de que um ecossistema aberto precisa e um perfil fechado não.
Assinar dados ligados
Uma credencial também tem de ser assinada, e o modelo de dados deixa aí uma escolha deliberada. Uma prova envolvente embrulha toda a credencial num contentor de assinatura como um JWT. Os bytes são assinados exatamente como estão, pelo que tudo o que os reordene ou reformate pelo caminho quebra a assinatura.
Uma prova Data Integrity incorporada funciona ao contrário. O documento é primeiro colocado numa forma canónica, definida pela RDF Dataset Canonicalization e W3C Recommendation desde 21 de maio de 2024, e a assinatura cobre essa forma em vez dos bytes. Como a forma canónica não depende da ordem das chaves, dos espaços nem dos nomes curtos que o @context use, a assinatura sobrevive a ser escrita de novo noutro sítio.
O seu lugar na EUDI Wallet
Não onde a maioria das pessoas supõe. O Architecture and Reference Framework indica dois formatos de credencial para a carteira europeia, SD-JWT VC e mdoc, e nenhum deles é JSON-LD. Uma organização que emita hoje para a EUDI Wallet não vai encontrar nenhum @context pelo caminho.
O raciocínio é a facilidade de implementação. Ambos os formatos têm uma estrutura fixa, um único mecanismo de assinatura e nenhum documento que um verificador tenha de ir buscar antes de poder verificar seja o que for. Para uma carteira que corre num telemóvel e um verificador que tem de responder em milissegundos, isso vale mais do que um vocabulário aberto.
O JSON-LD ganha o seu lugar onde os dados têm de viajar para além do ecossistema que os definiu: passaportes de produto e dados da cadeia de abastecimento, pilotos intersetoriais e tipos de credencial que nenhum perfil central alguma vez vai enumerar. Os dois mundos sobrepõem-se mais vezes do que competem, e as organizações que trabalham em ambos acabam normalmente por suportar os dois.
O outro JSON-LD, aquele que já usou
Muito antes das credenciais, o JSON-LD tornou-se a forma de um sítio web dizer a um motor de busca sobre o que é uma página. Um bloco dele no código-fonte da página, com o vocabulário de schema.org, é o que transforma uma página num artigo, produto, evento ou organização reconhecidos. Esta página tem um.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "JSON-LD explicado",
"description": "O que o JSON-LD acrescenta ao JSON simples, como um @context dá a cada campo um só significado e onde as credenciais verificáveis o usam.",
"image": "https://www.credenco.com/images/og-default.jpg",
"datePublished": "2026-10-15",
"dateModified": "2026-10-15",
"inLanguage": "pt",
"mainEntityOfPage": "https://www.credenco.com/pt/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"
}
}
}É o mesmo formato com um vocabulário diferente, e é a forma mais clara de perceber a ideia. Ninguém aqui acordou nada com nenhum motor de busca. O @context aponta para schema.org, o motor de busca já conhece esse vocabulário, e a página é compreendida por uma parte com quem nunca falou. Uma credencial que atravessa uma fronteira faz exatamente o mesmo.
O que lhe custa
O contexto tem de estar disponível. Um verificador que o vá buscar no momento da verificação acrescentou uma dependência de rede a uma decisão de segurança, e quem servir esse documento pode alterar o que a credencial parece dizer. As instalações reais fixam os contextos que aceitam e distribuem-nos com o software em vez de os resolverem em direto.
A canonização também é trabalho a sério. Transformar um documento num conjunto de dados canónico antes de o assinar é bastante mais código do que assinar bytes, e os seus modos de falha são subtis. Os documentos são também maiores, o que começa a pesar num código QR ou num toque NFC.
Nada disto faz do JSON-LD a escolha errada. Faz dele uma escolha: pague por vocabulários abertos onde os dados têm de sobreviver ao acordo que os criou, e dispense-os onde um perfil fixo já diz tudo o que as duas partes precisam.
O que isto significa para si
Emissor
Emitir para a EUDI Wallet significa SD-JWT VC ou mdoc, e o JSON-LD nunca entra em cena. Emitir para um ecossistema W3C faz do seu @context um compromisso de longo prazo: é a definição pública dos seus campos, e alterá-lo quebra todos os verificadores que guardaram a versão antiga em cache.
Verificador
Decida que contextos aceita e distribua-os com o seu software. Ir buscar um durante a verificação torna um servidor remoto parte da sua decisão de segurança e coloca uma chamada de rede a meio do seu tempo de resposta.
Programador
Leia um documento JSON-LD como JSON comum quando só precisa de um campo, e recorra a um processador completo apenas onde expande ou canoniza mesmo. A maior parte da complexidade que se atribui ao JSON-LD está no caminho da assinatura, não no da leitura.
Termos relacionados
Perguntas frequentes
O JSON-LD continua a ser simplesmente JSON?
Sim. Qualquer documento JSON-LD é JSON válido, e software que apenas precisa de ler um campo pode tratá-lo como tal. O maquinismo extra só entra em cena quando se expande um documento para a sua forma completa ou se canoniza o documento para o assinar, algo que a maior parte do código que lê uma credencial nunca faz.
A EUDI Wallet usa JSON-LD?
Não. O Architecture and Reference Framework indica SD-JWT VC e mdoc como formatos de credencial, e nenhum deles usa JSON-LD. Importa para os ecossistemas W3C de credenciais verificáveis, para os passaportes de produto e para os dados da cadeia de abastecimento, não para a carteira europeia em si.
Um verificador descarrega o @context de cada vez?
Não deve. Obter um contexto durante a verificação coloca uma chamada de rede dentro de uma decisão de segurança e dá a um servidor remoto a possibilidade de alterar o que o documento parece dizer. As implementações fixam os contextos que aceitam e distribuem-nos com o software, o que também elimina a latência.
É o mesmo JSON-LD que os motores de busca leem?
O mesmo formato com um vocabulário diferente. Os dados estruturados de uma página web apontam o seu @context para schema.org, enquanto uma credencial o aponta para o vocabulário de credenciais e para o mais que precise. As regras de processamento são idênticas nos dois casos.
Fontes
Esta página é informativa e não constitui aconselhamento jurídico. Para orientação com valor normativo, consulte diretamente as especificações do W3C.