# Come aggiungere schema markup senza rompere il sito

Lo schema markup è un blocco JSON-LD che descrive la pagina a una macchina. Ecco come aggiungerlo, validarlo e non rompere l'HTML.

> Pagina: https://ui.eneawork.it/blog/come-aggiungere-schema-markup
> Markdown: https://ui.eneawork.it/blog/come-aggiungere-schema-markup.md

*2026-11-01*

Lo schema markup è un blocco di dati strutturati, di solito JSON-LD, che descrive a una macchina cosa rappresenta la pagina senza cambiare ciò che l'utente vede. Si aggiunge con uno script nel documento e si valida prima del deploy.

Il catalogo EneUI conta 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, letti da /api/stats il 1 novembre 2026. La query «schema markup» compare nelle liste Google Autocomplete inglese e italiana registrate il 31 ottobre 2026 in docs/keyword-data.json. Lo stesso dataset non contiene una domanda Stack Overflow con voti su schema markup: i 16 tag campionati non includono seo o webmasters.

## Il formato: JSON-LD

Google documenta tre sintassi, JSON-LD, microdata e RDFa, e raccomanda JSON-LD. Il blocco vive in un <script type="application/ld+json"> e non deve essere annidato in un altro script. Il vocabolario è schema.org, licenza CC BY-SA 3.0; la documentazione di Google Search Central, proprietaria ma gratuita, elenca i tipi che producono un rich result.

## Il blocco minimo

{ "@context": "https://schema.org", "@type": "Article", "headline": "Article headline", "datePublished": "2026-11-01", "dateModified": "2026-11-01", "author": { "@type": "Person", "name": "Enea Zani", "url": "https://eneawork.it" } }

## Dove metterlo in Next.js

In un server component, renderizza lo script con dangerouslySetInnerHTML e serializza l'oggetto con JSON.stringify. Sostituisci ogni < con \u003c: senza questa sostituzione una stringa che contiene </script> chiude il blocco e rompe la pagina. Il componente next/script non serve, perché JSON-LD è un dato da leggere nel documento iniziale, non codice da caricare.

## Come verificarlo prima del deploy

cat > check-jsonld.mjs ]*application\/ld\+json[^>]*>([\s\S]*?)/g)]; for (const [i, block] of blocks.entries()) { JSON.parse(block[1]); console.log(`JSON-LD ${i}: valid`); } console.log(`${blocks.length} blocks parsed`); EOF curl -s https://ui.eneawork.it/ > page.html node check-jsonld.mjs page.html

Lo script legge il file HTML, estrae ogni blocco application/ld+json e chiama JSON.parse. Un errore di sintassi compare con il numero del blocco; un blocco valido non garantisce che Google lo usi, ma un blocco invalido garantisce che non lo usi. Per i rich result usa il Rich Results Test e lo Schema Markup Validator, entrambi gratuiti.

## Cosa Google usa davvero

Google non usa ogni tipo di schema.org. I rich result coprono un sottoinsieme documentato, per esempio Article, BreadcrumbList, Product, Event e Recipe. Da agosto 2023 i rich result FAQ sono limitati a siti governativi e sanitari autorevoli; da settembre 2023 i rich result HowTo sono stati rimossi. Aggiungere FAQPage a un blog non produce più le domande espandibili in SERP, anche se il markup resta utile per descrivere l'entità.

## Il catalogo EneUI

Per una pagina di prodotto o una FAQ il catalogo offre record reali: FAQ di Kokonut UI, licenza MIT, e la categoria FAQ dentro i 1.556 blocchi del catalogo. Un accordion non genera FAQPage da solo: il markup va aggiunto leggendo le domande visibili, e deve corrispondere al testo in pagina. Dati verificati il 1 novembre 2026.

## La limitazione

Lo schema markup descrive, non garantisce. Google può ignorare un tipo non supportato, limitare un rich result o applicare un'azione manuale se il markup contraddice il contenuto visibile; nessun validatore vede quella differenza, perché il confronto è semantico e lo fa una persona.

## Dove continuare

La sequenza per farsi indicizzare è in indicizzare un sito su Google; il posto dei metadati in App Router è in struttura Next.js App Router. Se il sito è su WordPress o su componenti React, il confronto è in WordPress, Wix o componenti React.

## FAQ

### Dove va inserito il JSON-LD?

Nel documento HTML, dentro un tag script con type application/ld+json. Può stare in head o in body: Google legge entrambi, purché il blocco non sia annidato in un altro script.

### Devo aggiungere FAQPage a ogni pagina?

No. Aggiungilo solo se la pagina contiene domande e risposte visibili. La restrizione di Google limita i rich result FAQ ai siti governativi e sanitari autorevoli.

### Lo schema markup migliora il ranking?

No, non è un fattore di ranking diretto. Aiuta Google a capire l'entità e può produrre rich result, che cambiano il modo in cui il risultato appare.

### Posso avere più blocchi JSON-LD nella stessa pagina?

Sì. Puoi usare un blocco per tipo o un unico @graph; l'importante è che gli identificatori non duplichino la stessa entità con dati diversi.

### Come trovo un errore di sintassi?

Estrai il blocco e passalo a JSON.parse: il messaggio indica posizione e carattere. Gli strumenti di Google segnalano errori di sintassi e proprietà mancanti, non un markup che contraddice il testo visibile.