I dati strutturati Schema.org: come implementarli

Una volta compreso il principio dei dati strutturati, resta la domanda pratica: quali tipi di Schema.org implementare per primi, come scrivere il JSON-LD corrispondente e come verificare che il markup sia valido.

I tipi prioritari

Cinque tipi coprono la grande maggioranza delle esigenze di un sito:

• Organization: l'identità dell'azienda (nome, logo, social, contatti) — generalmente impostata una sola volta, sulla homepage o a livello globale.
• Product: una scheda prodotto, con prezzo, disponibilità e recensioni.
• FAQPage: un elenco di domande e risposte, particolarmente utile per essere ripreso direttamente in una risposta di IA generativa.
• Article: contenuto editoriale (blog, notizie, guida), con autore, data di pubblicazione e di aggiornamento.
• BreadcrumbList: il percorso di navigazione, che rende esplicita la posizione di una pagina nella gerarchia del sito.

Esistono altri tipi per esigenze più specifiche: Event per un evento con data e luogo, LocalBusiness per un'attività con indirizzo fisico e orari, Review per una recensione individuale distinta da una valutazione aggregata, o HowTo per un contenuto strutturato in passaggi. Meglio implementare correttamente i cinque tipi prioritari prima di estendere il markup a tipi più specializzati, il cui beneficio dipende fortemente dal settore di attività.

Esempio JSON-LD commentato

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Nome del prodotto",
  "description": "Descrizione breve e fattuale del prodotto.",
  "brand": {
    "@type": "Brand",
    "name": "NomeMarca"
  },
  "offers": {
    "@type": "Offer",
    "price": "99.00",
    "priceCurrency": "EUR",
    "availability": "https://schema.org/InStock"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.6",
    "reviewCount": "128"
  }
}
</script>

Ogni proprietà deve riflettere un'informazione realmente presente e verificabile sulla pagina: il prezzo visualizzato deve corrispondere al prezzo marcato, la valutazione media deve corrispondere a recensioni reali e consultabili.

Per una pagina di domande frequenti:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Quanto tempo richiede l'attivazione?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "L'attivazione richiede generalmente tra 2 e 5 giorni lavorativi a seconda della complessità del progetto."
      }
    }
  ]
}
</script>

Dove inserire il codice

Il JSON-LD si inserisce generalmente nell'<head> o subito prima della chiusura del <body>, senza alcuna dipendenza dall'impaginazione visiva della pagina — a differenza di un markup HTML5 semantico, che resta strettamente legato alla struttura visiva del documento. Questo è uno dei vantaggi del JSON-LD rispetto alle sintassi alternative (microdata, RDFa) che richiedono di annotare direttamente i tag HTML visibili. Questa indipendenza dal rendering visivo permette anche di generarlo dinamicamente a partire da un database (scheda prodotto, sistema di gestione dei contenuti) senza intervento manuale su ogni pagina, il che lo rende una soluzione particolarmente adatta a siti con un numero elevato di pagine simili.

Strumenti di validazione

Prima della pubblicazione, sono necessari due controlli: la validazione sintattica (il JSON è ben formato, senza virgole superflue né virgolette mancanti) e la validazione semantica (i tipi e le proprietà utilizzati esistono nel vocabolario Schema.org e sono coerenti tra loro). Gli strumenti di test dei rich result di Google e i validatori Schema.org della community permettono di individuare entrambe le categorie di errori prima della pubblicazione, e di verificare che non manchi nessuna proprietà obbligatoria per il tipo utilizzato.

Questo controllo merita di essere ripetuto dopo ogni modifica del template che genera il markup, non solo al momento dell'implementazione iniziale: un aggiornamento del CMS, un cambiamento nella struttura del database o un aggiornamento del tema possono rompere silenziosamente un blocco JSON-LD generato dinamicamente, senza che nulla lo segnali visivamente sulla pagina.

Combinare più tipi sulla stessa pagina

Una pagina può legittimamente contenere più blocchi Schema.org contemporaneamente: una scheda prodotto può combinare Product per la scheda stessa, BreadcrumbList per il percorso di navigazione, e Organization per l'identità del brand che la vende. Questi blocchi possono essere dichiarati separatamente in più tag <script>, oppure raggruppati in un unico blocco tramite la proprietà @graph, che permette di collegare esplicitamente più entità tra loro all'interno di un solo documento JSON-LD. Questo secondo approccio diventa preferibile non appena le entità devono fare riferimento l'una all'altra (l'autore di un articolo, il brand di un prodotto), perché evita la duplicazione delle informazioni tra più blocchi indipendenti.

Errori frequenti

• Markup duplicato o contraddittorio tra più blocchi JSON-LD sulla stessa pagina.
• Dati marcati che non corrispondono più al contenuto visibile dopo un aggiornamento (prezzo cambiato sulla pagina ma non nel JSON-LD).
• Utilizzare un tipo Schema.org che non corrisponde realmente al contenuto (marcare una pagina del blog come Product).
• JSON malformato che invalida silenziosamente l'intero blocco.
• Moltiplicare i tipi secondari prima di aver correttamente implementato e validato i tipi prioritari.

Questa lezione chiude la parte dedicata al markup tecnico del modulo. La checklist tecnica completa che segue riprende tutti i punti trattati finora in forma di lista operativa, prima di passare ai fondamenti veri e propri del GEO.