Come creare una Skill Codex per SEO Schema JSON-LD

Risposta breve: lo Schema deve essere una copia strutturata dei fatti della pagina

Se sei arrivato qui cercando un prompt Codex SKILL.md per SEO Schema JSON-LD, puoi copiarne uno qui sotto. La regola che lo guida conta piu del codice: i dati strutturati devono esprimere fatti che un visitatore puo gia verificare nella pagina. Non sono un'occasione per creare l'oggetto JSON piu elaborato possibile.

Codex e utile perche puo ispezionare la pagina, i dati dei contenuti e il markup esistente prima di proporre un tipo o scrivere JSON-LD. Questo ordine conta. Una richiesta vaga come "aggiungi tutto lo schema possibile" spesso produce campi aggregateRating, prezzo, autore o data di pubblicazione inventati. Possono essere sintatticamente validi e rappresentare comunque la pagina in modo scorretto.

Google consiglia JSON-LD quando la configurazione del sito lo permette, perche in genere e piu semplice da implementare e mantenere. Le sue linee guida chiariscono anche che il markup deve descrivere la pagina in cui si trova, riflettere i contenuti visibili agli utenti e restare accurato. Superare il Rich Results Test non garantisce un risultato avanzato.

Scegli il tipo principale della pagina prima di aggiungere oggetti di supporto

Inizia da una domanda semplice: cosa sta guardando principalmente il visitatore? La risposta dovrebbe determinare il tipo Schema.org principale. Breadcrumb, dati dell'organizzazione e video possono supportare quell'oggetto principale quando descrivono informazioni che il visitatore vede nella stessa pagina.

Schema.org offre un vocabolario molto piu ampio delle funzionalita Google per i risultati avanzati. Per il lavoro su Google Search, la guida Google Search Central aggiornata per la funzionalita desiderata e piu autorevole del semplice fatto che una proprieta esista in Schema.org.

Parti dallo scopo della pagina. Il tipo segue i fatti visibili, non il contrario.

Un workflow Codex piu sicuro ha quattro controlli

1. Inventario dei fatti. Estrai solo dal testo visibile della pagina, da campi CMS attendibili renderizzati nella pagina o da dati che un utente ha verificato esplicitamente. Contrassegna ogni campo candidato come confermato, mancante o da confermare.
2. Decisione sul tipo. Scegli il tipo principale che corrisponde allo scopo centrale della pagina. Spiega ogni alternativa invece di accumulare tutti i tipi plausibili in una risposta.
3. Codice e mappatura. Produci JSON-LD con una fonte per ciascun valore emesso. Ometti le proprieta sconosciute anziche riempirle con segnaposto.
4. Convalida e rilascio. Controlla la sintassi JSON, i requisiti specifici della funzionalita, il DOM renderizzato, URL Inspection e il report Search Console appropriato.

La Skill seguente rende espliciti questi controlli. Chiede a Codex di fare prima l'audit e poi di modificare il codice, il modo piu semplice per evitare che un markup apparentemente valido si allontani dalla pagina reale.

Copia questa Skill Codex per SEO Schema JSON-LD (SKILL.md)

Salva quanto segue come configurazione della tua Skill. Non contiene directory della macchina, nome utente, token di accesso, valore di variabile d'ambiente o percorso privato. Indica anche a Codex di rimuovere il contesto sensibile dai suoi output.

---
name: seo-schema-jsonld
description: Audit visible page facts, recommend accurate Schema.org JSON-LD, implement it safely, and validate it against Google structured-data requirements.
---

# SEO Schema JSON-LD

Use this skill when a user asks to add, repair, review, or validate Schema.org JSON-LD / structured data for a website page, template, CMS entry, or component.

## Primary rule

Treat structured data as a structured representation of the page's user-visible facts. Never use it to invent, hide, exaggerate, or imply information that the page does not support.

## Privacy and output safety

- Never print absolute local paths, home directories, usernames, credentials, tokens, cookies, API keys, environment-variable values, private URLs, or repository-specific secrets.
- Refer to files with short, project-relative labels when needed, such as `src/pages/article.tsx` or `the page template`.
- Do not copy sensitive values into JSON-LD, examples, logs, commit messages, screenshots, or explanations.
- If input contains secrets or private identifiers, omit them and state that sensitive values were excluded.

## Required workflow

### 1. Inspect before generating

Read the relevant page, template, content data, and any existing structured data. Build a fact inventory using only:

- visible page text and user-visible UI;
- trusted CMS fields that are rendered on that page;
- verified product, organization, author, or breadcrumb data supplied by the user.

For every candidate property, label it `confirmed`, `missing`, or `needs human confirmation`. Do not infer missing values from brand names, URLs, conventions, or unrelated pages.

### 2. Choose the narrowest suitable type

Identify the page's primary purpose first. Recommend one primary Schema.org type that truthfully describes it. Add supporting objects only when they also describe user-visible information on the same page.

Explain the recommended primary type, supporting types, why each applies, and types deliberately rejected.

For Google rich-result eligibility, consult the current Google Search Central documentation for the target feature. Schema.org support alone does not establish Google feature support.

### 3. Apply strict data guardrails

Never generate these values unless they are confirmed and visible or otherwise explicitly verified by the user:

- `aggregateRating`, `review`, or review counts;
- price, currency, availability, offer dates, shipping, or return policy;
- author, publisher, logo, address, phone, social profile, or `sameAs`;
- publication dates, modification dates, images, video duration, or interaction counts;
- FAQ questions and answers that are not visibly present;
- event, job, medical, financial, legal, or local-business claims.

Never add misleading `FAQPage`, fake reviews, hidden content, keyword lists, or unrelated types. Prefer fewer complete and accurate properties over many uncertain ones.

### 4. Produce the implementation

Return these sections in order:

1. `Fact inventory` - property, value or status, and visible source.
2. `Schema decision` - primary type, supporting types, assumptions, and exclusions.
3. `JSON-LD` - valid JSON inside one `application/ld+json` script block. Use placeholders only in a clearly labeled illustrative example; never present placeholders as production-ready values.
4. `Implementation note` - the safe insertion point for the site's framework or CMS, without exposing private paths.
5. `Validation checklist` - syntax, rendered-page check, Google Rich Results Test when applicable, Schema Markup Validator, URL Inspection after deployment, and Search Console monitoring.
6. `Open questions` - every field that needs a human decision.

If editing code is requested, make the smallest scoped change. Preserve existing valid markup, avoid duplicate entities, and explain any conflict before replacing it.

## JSON-LD quality checks

Before finalizing, verify all of the following:

- JSON parses and uses `https://schema.org` as `@context`.
- The main type matches the page's main user-visible purpose.
- Every emitted value has a page-level source or explicit user confirmation.
- Required fields for the intended Google feature are present and accurate.
- URLs are canonical, publicly reachable URLs when the property requires a URL.
- Dates use ISO 8601 where required.
- Multiple entities are connected deliberately, not duplicated accidentally.
- The markup remains available to crawlers in the rendered response.
- The result contains no secrets, local paths, private identifiers, or fabricated claims.

## Limitations to state plainly

Valid structured data can help search engines understand a page and make it eligible for certain search appearances. It does not guarantee rich results, rankings, traffic, citations, or inclusion in AI answers.

Usa la Skill con un passaggio di approvazione

Non fermarti a "aggiungi schema a questa pagina". Fornisci a Codex la pagina e i criteri di accettazione. Questo e un utile prompt iniziale:

Use the SEO Schema JSON-LD skill to review this article page.

Goal: add accurate Article and BreadcrumbList JSON-LD if the visible content supports them.
First return the fact inventory and schema decision. Do not edit code until I approve the decision.
Do not create ratings, reviews, author details, dates, images, or organization fields that are absent from the page.
After approval, make the smallest implementation change and provide the validation checklist.

Per un template di grandi dimensioni, mantieni il controllo "inventario dei fatti e decisione prima". Aggiunge una breve revisione, ma puo impedire che una cattiva supposizione si diffonda su migliaia di URL.

Un percorso di 30 minuti dall'audit al rilascio

Dopo il rilascio, usa URL Inspection per confermare che Google possa recuperare e analizzare la pagina. Poi usa il report sui miglioramenti pertinente in Search Console per trovare su larga scala problemi di template, distribuzione o fonte dati. Il primo controlla un URL singolo; il secondo e piu adatto a rilevare problemi sistemici.

Ogni livello intercetta un errore diverso. Un oggetto sintatticamente valido puo comunque fallire il controllo dei fatti della pagina o della distribuzione.

Un esempio volutamente minimo per una pagina articolo

Questo e codice illustrativo, non un oggetto di produzione pronto da incollare. Mostra la forma di BlogPosting e BreadcrumbList. Usa valori reali confermati dalla pagina per titolo, descrizione, URL, autore, data e immagine. Se la pagina non contiene uno di questi fatti, non aggiungerlo solo per far sembrare l'oggetto piu completo.

L'esempio non include intenzionalmente valutazione, autore, data di pubblicazione, immagine o publisher. Non sono decorazioni SEO facoltative: sono affermazioni che richiedono una fonte affidabile.

Cinque modi in cui un markup tecnicamente valido puo comunque andare storto

Il parsing JSON non e un test di verita

Un validatore JSON puo dirti se la sintassi viene analizzata. Non puo dirti se la pagina contiene le recensioni, il prezzo o l'autore dichiarati, o se un Product e in realta solo una pagina descrittiva di un servizio. L'inventario dei fatti intercetta presto la maggior parte di questi errori.

Piu oggetti non significano markup migliore

Una pagina di ricetta con un video visibile puo includere legittimamente Recipe, VideoObject e breadcrumb. Il suo scopo principale dovrebbe comunque restare chiaro. Aggiungere Article, Product, FAQPage e HowTo a una pagina di contenuti generica di solito crea lavoro di manutenzione e rischio di incoerenza.

Visibilita e aggiornamento richiedono lo stesso responsabile

Le linee guida generali di Google richiedono che i dati strutturati rappresentino la pagina e che le informazioni sensibili al tempo restino aggiornate. Prezzi, disponibilita, date di eventi, offerte di lavoro e valutazioni non dovrebbero esistere come valori incollati una sola volta. Collega i fatti dinamici a una fonte controllata e ripeti i test quando il template cambia.

FAQPage non e una decorazione generica di domande e risposte

Solo domande e risposte che gli utenti possono davvero vedere appartengono al markup FAQ, e le funzionalita Google possono avere ulteriori condizioni di idoneita. Pubblica prima una FAQ autentica e completa, poi controlla la guida aggiornata della funzionalita. Non progettare una lista di domande solo per ottenere un trattamento nei risultati.

Schema non aggira crawling, indicizzazione o qualita della pagina

Una pagina importante bloccata da noindex, controlli di accesso o regole di crawling non diventa idonea ai risultati di ricerca solo perche contiene JSON-LD. Schema e uno strato della SEO tecnica. Non sostituisce crawlability, contenuti utili o esperienza di pagina. Per un controllo piu ampio del sito, usa la directory degli strumenti SEO di Auspia per scegliere il workflow di audit adatto.

Checklist prima della pubblicazione

• [ ] Il tipo principale della pagina e indicato e puo essere giustificato in una frase.
• [ ] Ogni valore JSON-LD ha una fonte visibile nella pagina o una fonte dati affidabile e renderizzata.
• [ ] Non sono stati inventati valutazioni, recensioni, prezzo, disponibilita, autore, data, immagine o dettagli dell'organizzazione.
• [ ] La modifica non duplica entita gia emesse da CMS, plugin o altri componenti.
• [ ] Il JSON e valido e il markup appare nel DOM renderizzato simile alla produzione.
• [ ] Le proprieta obbligatorie per la funzionalita Google desiderata sono state controllate nella documentazione ufficiale aggiornata.
• [ ] Sono stati usati il Rich Results Test, quando pertinente, e Schema Markup Validator.
• [ ] Sono programmati URL Inspection e una revisione Search Console dopo il rilascio.
• [ ] Il team comprende che un markup valido crea idoneita e chiarezza, non una promessa di risultato avanzato o ranking.

Domande frequenti

Un SKILL.md puo decidere quale schema serve al mio sito?

Puo fare una raccomandazione a partire dai fatti della pagina e identificare le incognite, ma non dovrebbe sostituire la conferma dei fatti. Prezzi dei prodotti, recensioni, dati dell'organizzazione, autori e date di pubblicazione dovrebbero provenire da una fonte dati affidabile nella pagina o dal responsabile delle informazioni.

Il JSON-LD deve stare nel <head> o nel <body>?

Google supporta JSON-LD sia nel <head> sia nel <body> HTML. Usa la posizione stabile che framework o CMS riescono a mantenere sincronizzata con la pagina. Il test significativo e se Google puo eseguire il crawling di markup valido che corrisponde alla pagina renderizzata.

Perche non e cambiato nulla dopo il superamento del Rich Results Test?

Un test superato conferma segnali di idoneita tecnica; non obbliga Google a mostrare un risultato avanzato. Google seleziona i trattamenti dei risultati con molti segnali, tra cui query, dispositivo, localita e la pagina stessa. Controlla coerenza dei contenuti e indicizzabilita invece di aggiungere proprieta non supportate.

Codex dovrebbe compilare ogni proprieta Schema.org che trova?

No. La documentazione Google privilegia un numero minore di proprieta consigliate, complete e accurate rispetto a molte proprieta incomplete o inaccurate. Questo vincolo deve stare nella Skill, non solo in un prompt occasionale.

Riferimenti ufficiali

• Google Search Central: Introduction to structured data markup
• Google Search Central: General structured data guidelines
• Google Rich Results Test
• Schema.org

Autore: Julian Mercer, professionista SEO tecnico con 14 anni di esperienza in Auspia. Julian scrive di crawling, rendering, dati strutturati e sistemi tecnici che i team possono gestire in modo affidabile.