JSON-LD spiegato
JSON-LD è normale JSON con una riga in più che dice che cosa significano i campi. Quella riga trasforma un nome di campo locale in uno definito a livello globale, così un sistema che non ha mai visto i vostri dati riesce comunque a capire di che cosa state parlando. È uno standard del W3C dal 2014, è il modo in cui i motori di ricerca leggono proprio questa pagina ed è ciò su cui si fonda il modello di dati del W3C per le credenziali verificabili.
Il problema del JSON semplice
JSON dice come si scrivono i dati. Non dice nulla su che cosa significhino. Un campo chiamato name può essere una persona, un'azienda o un prodotto. Un campo chiamato id può essere un numero cliente, un numero di passaporto o una riga nel database di qualcuno. Due sistemi possono produrre entrambi JSON perfettamente valido e non essere d'accordo su nessuno dei suoi campi.
In pratica quel divario si colma con un accordo. Le due parti mettono per iscritto che cosa significano i campi e costruiscono il software di conseguenza. Funziona per una integrazione, diventa costoso a dieci e smette del tutto di funzionare quando una credenziale emessa in un paese deve essere compresa da un verificatore di un altro paese con cui nessuno ha parlato prima.
Che cosa fa il @context
JSON-LD colma quel divario dentro il documento stesso. Un @context associa ogni nome di campo abbreviato a un identificatore univoco a livello mondiale, di norma un URL controllato da chi ha definito il vocabolario. Il campo resta breve e leggibile per una persona e diventa inequivocabile per una macchina.
JSON semplice
{
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Valido, leggibile e privo di significato per chiunque non sia stato informato in anticipo di che cosa dovrebbero contenere i campi.
Gli stessi dati in JSON-LD
{
"@context": "https://schema.org",
"@type": "Person",
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Ogni campo punta ora a una definizione pubblicata, così un sistema che non ha mai visto questo documento riesce comunque a leggerlo correttamente.
- @context indica il vocabolario in cui è definito ogni campo del documento.
- @type dice che tipo di cosa descrive il documento, in modo che da quel vocabolario vengano prese le definizioni giuste.
Nei dati in sé non cambia nulla. Gli stessi valori nella stessa forma portano ora un rimando alla definizione di ogni campo. Un sistema ricevente che riconosce il vocabolario sa esattamente che cosa gli è stato consegnato, e uno che non lo riconosce può comunque leggere il documento come normale JSON e ignorare il resto.
L'idea è tutta qui. Il significato viaggia con il documento invece di risiedere in una specifica su cui le due parti dovevano mettersi d'accordo in anticipo.
Dove compare nelle credenziali verificabili
Il W3C Verifiable Credentials Data Model 2.0, W3C Recommendation dal 15 maggio 2025, è costruito su JSON-LD. Ogni credenziale si apre con un @context il cui primo valore è il vocabolario condiviso delle credenziali, così i termini comuni a tutte le credenziali, l'emittente, il soggetto, le date di validità e le informazioni di stato, significano la stessa cosa ovunque.
Tutto il resto viene da un secondo vocabolario. Un'università ne pubblica uno per i campi dei diplomi, una camera di commercio uno per i campi della registrazione d'impresa. Un verificatore interessato ai diplomi carica il primo, uno interessato ai dati d'impresa carica il secondo, e nessuno dei due deve cambiare quando l'altro aggiunge un campo.
È questo che permette a un solo formato di credenziale di trasportare dati che nessuno aveva previsto quando il formato è stato scritto, ed è la proprietà di cui un ecosistema aperto ha bisogno e un profilo chiuso no.
Firmare dati collegati
Anche una credenziale va firmata, e il modello di dati lascia lì una scelta deliberata. Una prova avvolgente racchiude l'intera credenziale in un contenitore di firma come un JWT. I byte vengono firmati esattamente come sono, quindi tutto ciò che li riordina o li riformatta lungo la strada rompe la firma.
Una prova Data Integrity incorporata funziona al contrario. Il documento viene prima portato in una forma canonica, definita da RDF Dataset Canonicalization e W3C Recommendation dal 21 maggio 2024, e la firma copre quella forma invece dei byte. Poiché la forma canonica non dipende dall'ordine delle chiavi, dagli spazi o dai nomi brevi che il @context usa, la firma sopravvive a una riscrittura altrove.
Il suo posto nell'EUDI Wallet
Non dove la maggior parte delle persone immagina. L'Architecture and Reference Framework indica due formati di credenziale per il portafoglio europeo, SD-JWT VC e mdoc, e nessuno dei due è JSON-LD. Un'organizzazione che oggi emette verso l'EUDI Wallet non incontrerà alcun @context lungo il percorso.
Il motivo è la realizzabilità. Entrambi i formati hanno una struttura fissa, un unico meccanismo di firma e nessun documento che un verificatore debba andare a recuperare prima di poter controllare qualcosa. Per un portafoglio che gira su un telefono e un verificatore che deve rispondere in millisecondi, questo vale più di un vocabolario aperto.
JSON-LD si guadagna il suo posto dove i dati devono viaggiare oltre l'ecosistema che li ha definiti: passaporti di prodotto e dati della catena di fornitura, progetti pilota intersettoriali e tipi di credenziale che nessun profilo centrale elencherà mai. I due mondi si sovrappongono più spesso di quanto competano, e le organizzazioni che lavorano in entrambi finiscono di solito per supportarli tutti e due.
L'altro JSON-LD, quello che avete già usato
Molto prima delle credenziali, JSON-LD è diventato il modo in cui un sito web dice a un motore di ricerca di che cosa parla una pagina. Un blocco di JSON-LD nel sorgente della pagina, con il vocabolario di schema.org, è ciò che trasforma una pagina in un articolo, un prodotto, un evento o un'organizzazione riconosciuti. Questa pagina ne contiene uno.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "JSON-LD spiegato",
"description": "Che cosa aggiunge JSON-LD al JSON semplice, come un @context dà a ogni campo un unico significato e dove lo usano le credenziali verificabili.",
"image": "https://www.credenco.com/images/og-default.jpg",
"datePublished": "2026-10-15",
"dateModified": "2026-10-15",
"inLanguage": "it",
"mainEntityOfPage": "https://www.credenco.com/it/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"
}
}
}È lo stesso formato con un vocabolario diverso, ed è il modo più chiaro per cogliere il punto. Qui nessuno ha concordato nulla con alcun motore di ricerca. Il @context punta a schema.org, il motore di ricerca conosce già quel vocabolario, e la pagina viene compresa da una parte con cui non ha mai parlato. Una credenziale che attraversa un confine fa esattamente la stessa cosa.
Quanto costa
Il contesto deve essere disponibile. Un verificatore che lo recupera al momento della verifica ha aggiunto una dipendenza di rete a una decisione di sicurezza, e chi serve quel documento può cambiare ciò che la credenziale sembra dire. Le installazioni reali fissano i contesti che accettano e li distribuiscono con il software invece di risolverli in diretta.
Anche la canonizzazione è lavoro vero. Trasformare un documento in un dataset canonico prima di firmarlo richiede molto più codice che firmare byte, e i modi in cui può fallire sono sottili. I documenti sono inoltre più grandi, il che inizia a contare su un codice QR o in un tocco NFC.
Niente di tutto questo rende JSON-LD la scelta sbagliata. Lo rende una scelta: pagate per vocabolari aperti dove i dati devono sopravvivere all'accordo che li ha creati, e fatene a meno dove un profilo fisso dice già tutto ciò che alle due parti serve.
Che cosa significa per te
Emittente
Emettere verso l'EUDI Wallet significa SD-JWT VC o mdoc, e JSON-LD non entra mai in gioco. Emettere verso un ecosistema W3C rende il vostro @context un impegno di lungo periodo: è la definizione pubblica dei vostri campi, e cambiarlo rompe ogni verificatore che ha messo in cache quella vecchia.
Verificatore
Decidete quali contesti accettate e distribuiteli con il vostro software. Recuperarne uno durante la verifica rende un server remoto parte della vostra decisione di sicurezza e mette una chiamata di rete in mezzo al vostro tempo di risposta.
Sviluppatore
Leggete un documento JSON-LD come normale JSON quando vi serve solo un campo, e ricorrete a un processore completo solo dove espandete o canonizzate davvero. La maggior parte della complessità che si attribuisce a JSON-LD sta nel percorso della firma, non in quello della lettura.
Termini correlati
Domande frequenti
JSON-LD è ancora semplicemente JSON?
Sì. Ogni documento JSON-LD è JSON valido, e un software che deve solo leggere un campo può trattarlo come tale. Il macchinario aggiuntivo entra in gioco quando si espande un documento nella sua forma completa o lo si canonizza per firmarlo, cosa che la maggior parte del codice che legge una credenziale non fa mai.
L'EUDI Wallet usa JSON-LD?
No. L'Architecture and Reference Framework indica SD-JWT VC e mdoc come formati di credenziale, e nessuno dei due usa JSON-LD. Conta per gli ecosistemi W3C di credenziali verificabili, per i passaporti di prodotto e per i dati della catena di fornitura, non per il portafoglio europeo in sé.
Un verificatore scarica il @context ogni volta?
Non dovrebbe. Recuperare un contesto durante la verifica mette una chiamata di rete dentro una decisione di sicurezza e dà a un server remoto la possibilità di cambiare ciò che il documento sembra dire. Le implementazioni fissano i contesti che accettano e li distribuiscono con il software, il che elimina anche la latenza.
È lo stesso JSON-LD che leggono i motori di ricerca?
Lo stesso formato con un vocabolario diverso. I dati strutturati di una pagina web puntano il loro @context a schema.org, mentre una credenziale lo punta al vocabolario delle credenziali e a quello che le serve in più. Le regole di elaborazione sono identiche in entrambi i casi.
Fonti
Questa pagina ha scopo informativo e non costituisce consulenza legale. Per indicazioni autorevoli consultate direttamente le specifiche del W3C.