Cos’è JSON-LD e come funziona

Cos’è JSON-LD, in breve

• Cos’è: un’estensione di JSON che aggiunge significato semantico tramite un contesto dichiarato con @context.
• Dove si inserisce: in un blocco <script type="application/ld+json">, nell’head o nel body della pagina.
• Vocabolario di riferimento: quasi sempre Schema.org, per descrivere tipi come Article, Product o LocalBusiness.
• A cosa serve: aiuta Google a generare risultati arricchiti nella ricerca e fornisce dati leggibili anche ai sistemi di intelligenza artificiale.
• Standard di riferimento: è una raccomandazione del W3C, attualmente alla versione 1.1.
• Come si verifica: con uno strumento di validazione dedicato, prima e dopo la pubblicazione della pagina.

JSON-LD e la differenza con JSON

JSON-LD nasce come estensione di JSON: ogni documento JSON-LD valido è anche un documento JSON valido, leggibile da qualunque parser standard. La differenza sta in quello che JSON-LD aggiunge sopra la sintassi di base: chiavi riservate come @context, @id e @type che collegano i dati a un vocabolario condiviso, in genere Schema.org. JSON da solo descrive una struttura di dati senza dire cosa significano quei dati per chi la legge dall’esterno; JSON-LD aggiunge quel livello di significato.

Lo standard è una raccomandazione del W3C, elaborata inizialmente da un gruppo di lavoro dedicato al linked data e poi passata all’RDF Working Group per la standardizzazione definitiva. Dietro al formato c’è il modello RDF, che rappresenta i dati come triple soggetto-predicato-oggetto: JSON-LD è il modo di scrivere quel modello con la sintassi JSON.

JSON non è un linguaggio di markup: è un formato dati testuale. JSON-LD viene usato come blocco separato dentro una pagina HTML, in una posizione simile a un linguaggio di markup, pur restando un documento JSON a tutti gli effetti. Confrontarlo con XML o YAML ha poco senso nel contesto SEO: sono altri formati di interscambio dati, pensati per API e configurazioni, non per collegare entità semantiche dentro una pagina web. Conviene partire sempre da qui quando si spiega JSON-LD a chi non ha un background tecnico: prima la base JSON, poi quello che ci si aggiunge sopra. JSON-LD fa parte degli esempi pratici di dati strutturati che un sito può implementare per descrivere i propri contenuti ai motori di ricerca.

Come funziona JSON-LD

Il blocco JSON-LD si inserisce dentro un tag <script type="application/ld+json">, che puoi mettere nell’head o nel body della pagina HTML. Google legge questo blocco senza che interferisca con il contenuto che l’utente vede: è la ragione per cui Google lo raccomanda come formato preferito per i dati strutturati rispetto a Microdati e RDFa, che invece richiedono attributi dentro i tag HTML esistenti.

Dentro il blocco, la chiave @context mappa le proprietà JSON a un vocabolario esterno: quando scrivi "@context": "https://schema.org" stai dicendo che le chiavi successive (name, author, address) vanno interpretate secondo le definizioni di Schema.org. La chiave @id assegna un identificatore univoco a un’entità, in forma di IRI: utile quando la stessa entità (un’organizzazione, una persona) compare in più pagine e vuoi che i sistemi la riconoscano come la stessa cosa. La chiave @type dichiara la classe semantica dell’entità descritta, per esempio Article, Product o LocalBusiness.

Se il JSON-LD lo genera un CMS o un plugin

Google legge il JSON-LD anche quando viene iniettato dinamicamente via JavaScript, per esempio da un plugin WordPress o dal template di un e-commerce: non serve che il codice sia scritto a mano nell’HTML statico. Se gestisci un sito WordPress, la parte pratica dell’inserimento è descritta nella guida su come integrare Schema Markup su WordPress. L’unica condizione è che il blocco risulti nel DOM renderizzato quando Google esegue la scansione della pagina, non solo nel codice sorgente iniziale.

JSON-LD, Microdati e RDFa a confronto

I tre formati fanno lo stesso lavoro, descrivere il contenuto di una pagina ai motori di ricerca, ma li scrivi in punti diversi del documento e con un impatto diverso sul codice.

JSON-LD è la scelta preferibile nella maggior parte dei progetti: mantenere il markup separato dal contenuto riduce gli errori quando qualcuno tocca il template HTML senza sapere che lì dentro c’è anche dello Schema.org. Con Microdati e RDFa basta spostare un tag per rompere il markup semantico senza accorgersene.

Esempio pratico di codice JSON-LD

Un blocco JSON-LD per un’attività locale si scrive più o meno così:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Nome dell'attività",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "Via Esempio 10",
    "addressLocality": "Milano",
    "postalCode": "20100",
    "addressCountry": "IT"
  },
  "telephone": "+39 02 1234567",
  "openingHours": "Mo-Fr 09:00-18:00"
}
</script>

Per arrivare a questo risultato, segui questo ordine di passaggi:

1. Individua il tipo di contenuto della pagina (articolo, prodotto, attività locale, evento) e il tipo Schema.org corrispondente.
2. Elenca le proprietà richieste e quelle consigliate per quel tipo, consultando la documentazione Google del tipo scelto.
3. Scrivi il blocco in formato JSON, aprendo con @context e @type.
4. Inserisci il blocco dentro un tag script con type="application/ld+json", nell’head o nel body della pagina.
5. Valida il codice con uno strumento di controllo prima di pubblicare la pagina.

I tipi Schema.org disponibili sono molti di più di quelli citati qui: Article, Product, Event, Recipe, Person e Organization sono i più usati, ma l’elenco completo e le proprietà di ciascuno sono descritti in modo più ampio nella pagina su Schema.org. Se gestisci un e-commerce su piattaforme come Shopify o WooCommerce, nella maggior parte dei casi il JSON-LD per i prodotti viene già generato dal tema o da un plugin: la parte che resta da fare è controllare che i dati generati corrispondano a quelli reali della scheda prodotto.

A cosa serve JSON-LD

JSON-LD serve a far capire a Google di che tipo di contenuto è fatta una pagina, in modo che possa mostrarla con elementi arricchiti nei risultati di ricerca: stelle di valutazione, prezzi, date di un evento, passaggi di una ricetta. La logica e gli esempi di questi risultati arricchiti sono trattati nella pagina sui rich snippet, dove entro nel dettaglio dei singoli tipi di risultato.

Fuori dalla ricerca pura, JSON-LD viene usato anche per scambiare dati tra servizi REST e database distribuiti senza ambiguità sul significato dei campi: due sistemi che condividono lo stesso contesto Schema.org interpretano “name” o “address” allo stesso modo. Lo stesso principio spiega perché un blocco JSON-LD ben strutturato può risultare utile anche ai sistemi di intelligenza artificiale che leggono una pagina: i dati sono già etichettati, invece di dover essere dedotti dal testo libero. Per questo se ne discute spesso nelle community di sviluppatori, soprattutto da quando i motori di risposta basati su intelligenza artificiale hanno iniziato a citare pagine web nelle loro risposte.

Controllare che il codice JSON-LD sia corretto e aggiornato rientra tra gli interventi di ottimizzazione tecnica del sito, insieme ad altre verifiche come l’indicizzabilità delle pagine e la risposta corretta del server.

Come validare un file JSON-LD

Un codice JSON-LD si valida in due passaggi: prima con uno strumento che controlla la sintassi JSON (parentesi, virgolette, virgole), poi con uno strumento che controlla la corrispondenza con Schema.org e con le proprietà richieste da Google per quel tipo specifico di risultato arricchito. Google mette a disposizione uno strumento dedicato, il test dei risultati avanzati, che segnala le proprietà mancanti o scritte in modo scorretto e mostra un’anteprima del possibile risultato in ricerca.

L’idoneità al risultato arricchito richiede anche tutte le proprietà obbligatorie per quel tipo di dati, secondo le linee guida che Google pubblica per ogni singola funzionalità. Consiglio di rifare il controllo dopo ogni modifica al template della pagina, non solo alla prima pubblicazione: un aggiornamento del tema o di un plugin può alterare il JSON-LD senza che nessuno se ne accorga subito.

Errori frequenti e casi limite di JSON-LD

L’errore più comune è una virgola in eccesso dopo l’ultima proprietà di un oggetto: JSON non la tollera, e un JSON-LD con quella virgola smette di essere JSON valido, quindi anche JSON-LD valido. Chiavi senza virgolette, apici singoli al posto di quelli doppi e commenti dentro il blocco script producono lo stesso risultato: un documento che il parser scarta senza leggerlo.

Un secondo errore riguarda i dati non visibili all’utente: Google sconsiglia di descrivere nel JSON-LD informazioni che non compaiono da nessuna parte nella pagina, anche se sono accurate. Il markup deve rispecchiare il contenuto reale, non aggiungere dati che esistono solo nel codice.

Vale la pena distinguere JSON-LD da JSONL, sigla diversa che indica JSON Lines, un formato dove ogni riga del file è un oggetto JSON a sé stante, usato per log e dataset di grandi dimensioni: non ha a che fare con i dati strutturati per la ricerca e non va confuso per somiglianza del nome.

Un ultimo caso limite riguarda il contesto: se ometti @context o lo scrivi con un URL sbagliato, le proprietà del documento restano senza un vocabolario di riferimento e Google non può interpretarle secondo Schema.org, anche se la sintassi JSON è corretta.

Domande frequenti su JSON-LD

Che cos’è JSON-LD?

JSON-LD è un formato per descrivere dati strutturati che estende JSON con un contesto semantico basato su Schema.org. Si usa per dichiarare a Google di che tipo è il contenuto di una pagina (articolo, prodotto, attività locale) senza modificare il markup visibile all’utente.

Che differenza c’è tra JSON e JSON-LD?

JSON è un formato dati generico, senza alcun significato collegato ai suoi campi al di fuori dell’applicazione che lo legge. JSON-LD aggiunge chiavi come @context e @type che collegano quei campi a un vocabolario condiviso, rendendoli interpretabili anche fuori dal contesto in cui sono stati creati.

JSON è considerato un linguaggio di markup?

JSON è un formato dati testuale. JSON-LD viene inserito in una pagina HTML in una posizione simile a quella di un linguaggio di markup, ma il documento al suo interno resta un file JSON.

JSON-LD è sempre JSON valido?

Sì, ogni documento JSON-LD scritto correttamente è anche un documento JSON valido e può essere letto da qualunque parser JSON standard. Un errore di sintassi JSON, come una virgola in eccesso, invalida entrambi allo stesso modo.

JSON-LD è obbligatorio per il posizionamento su Google?

JSON-LD serve a rendere idonea una pagina ai risultati arricchiti, senza agire come fattore di ranking diretto. Resta il formato che Google raccomanda quando un sito può scegliere tra JSON-LD, Microdati e RDFa.

Come si valida un file JSON-LD?

Si valida controllando prima la sintassi JSON, poi la corrispondenza con le proprietà richieste da Google per quel tipo di dato, tramite uno strumento di test dei risultati avanzati. Il controllo va ripetuto dopo ogni modifica al template della pagina.

JSON-LD è diverso da JSONL?

Sì, nonostante il nome simile: JSONL (JSON Lines) è un formato per elencare più oggetti JSON, uno per riga, usato per log e dataset. JSON-LD è un formato per dati strutturati semantici dentro una singola pagina web.

JSON-LD serve anche ai crawler delle intelligenze artificiali?

Un blocco JSON-LD ben scritto fornisce dati etichettati che possono essere utili anche ai sistemi di intelligenza artificiale, oltre che a Google, senza bisogno di interpretare testo libero. Per questo motivo è sempre più citato insieme ai temi della visibilità nei motori generativi di risposta.