Dati strutturati nel tempo: test, monitoraggio e regressioni

Aggiungere i dati strutturati a un sito è un lavoro di qualche giorno. Mantenerli corretti è un lavoro che non finisce mai. I template cambiano, i campi del CMS vengono rinominati, un plugin si aggiorna e duplica il markup, i motori modificano i requisiti dei risultati arricchiti. Senza un processo di controllo, dopo un anno il markup di molti siti è parzialmente rotto senza che nessuno se ne sia accorto.

Errori e avvisi non sono la stessa cosa

Gli strumenti di validazione distinguono due livelli:

Gli errori vanno corretti sempre. Gli avvisi vanno valutati: aggiungere una proprietà consigliata ha senso solo se il dato esiste davvero e compare sulla pagina. Inventare un valore per far sparire un avviso è peggio che lasciarlo.

Due strumenti con scopi diversi

• Validatori del vocabolario Schema.org: controllano che il markup sia sintatticamente corretto e che tipi e proprietà esistano nel vocabolario.
• Test dei risultati arricchiti dei motori: controllano se il markup soddisfa i requisiti specifici di quel motore per un certo tipo di risultato.

Un markup può essere perfettamente valido per Schema.org e non idoneo ad alcun risultato arricchito, perché il motore richiede proprietà aggiuntive o non supporta quel tipo. Conviene usare entrambi: il primo per la correttezza, il secondo per l'effetto nella ricerca.

Le regressioni più comuni

Nel mio lavoro, quando un markup che funzionava smette di farlo, la causa è quasi sempre una di queste:

1. campo vuoto nel CMS: il template genera "price": "" o "author": {"name": ""} perché un redattore ha lasciato vuoto un campo;
2. markup duplicato: un tema e un plugin generano entrambi un blocco Product o Organization, con valori diversi;
3. formato cambiato: una data che passa da 2026-03-12 a 12/03/2026, un prezzo con il simbolo della valuta dentro il numero;
4. dati non più visibili: recensioni o prezzi rimossi dalla pagina in un redesign ma rimasti nel JSON-LD;
5. URL relativi o vecchi: immagini e logo che puntano al dominio precedente dopo una migrazione;
6. caratteri non gestiti: virgolette o a capo nei testi che rompono il JSON se il template non li codifica.

Test automatici nella build

Il modo più affidabile di prevenire regressioni è controllare il markup prima che arrivi in produzione. Un approccio semplice:

1. scegli un campione rappresentativo di URL, una pagina per ogni template;
2. nella pipeline di build o in un test notturno, scarica l'HTML di quelle pagine dallo staging;
3. estrai i blocchi <script type="application/ld+json"> e verifica che siano JSON valido;
4. controlla la presenza delle proprietà essenziali per ciascun tipo e che non siano vuote;
5. fai fallire il test se qualcosa manca.

Un controllo minimale si scrive in poche righe:

import json, re, sys, urllib.request
html = urllib.request.urlopen(sys.argv[1]).read().decode()
blocks = re.findall(r'<script type="application/ld\+json">(.*?)</script>', html, re.S)
for b in blocks:
    data = json.loads(b)
    if data.get("@type") == "Product":
        assert data.get("name"), "Product senza nome"
        assert data.get("offers", {}).get("price"), "Product senza prezzo"
print("ok", len(blocks), "blocchi")

Non sostituisce i validatori ufficiali, ma intercetta subito i guasti più frequenti.

Il monitoraggio in produzione

Gli strumenti per webmaster offrono rapporti per ciascun tipo di dato strutturato rilevato, con il numero di elementi validi, con avvisi e non validi. Conviene:

• controllarli dopo ogni rilascio che tocca i template;
• osservare l'andamento nel tempo: un calo improvviso degli elementi validi indica una regressione;
• usare le notifiche via email per i nuovi errori.

Coerenza con il contenuto visibile

I dati strutturati devono descrivere ciò che l'utente vede sulla pagina. Valutazioni non presenti, prezzi diversi da quelli mostrati, eventi già conclusi, recensioni scritte dal sito su sé stesso: sono violazioni delle linee guida che possono portare alla perdita dei risultati arricchiti o a un'azione manuale. Il controllo automatico più utile, dove possibile, è confrontare il valore nel JSON-LD con quello estratto dall'HTML visibile.

Requisiti che cambiano

I motori aggiornano periodicamente i tipi di risultati arricchiti supportati e i loro requisiti; alcuni sono stati ridotti o ritirati nel tempo. Un markup corretto ma non più utilizzato non fa danni, ma non va considerato una garanzia di visibilità. Rivedi la documentazione ufficiale dei tipi che usi almeno una volta l'anno.

In sintesi

• Gli errori escludono dai risultati arricchiti; gli avvisi vanno valutati senza inventare dati.
• Usa sia un validatore Schema.org sia i test del motore: misurano cose diverse.
• Le regressioni nascono da campi vuoti, duplicati, formati e redesign.
• Aggiungi un test automatico sul JSON-LD dei template principali.
• Mantieni il markup coerente con il contenuto visibile e rivedi i requisiti ogni anno.