CM Structured Data

Motore di dati strutturati JSON-LD per WordPress, configurabile per sito e condiviso fra installazioni diverse.

Perché esiste

Nasce dal consolidamento di un sito su cui convivevano quattro generatori di schema diversi: un plugin SEO, un plugin di schema usato come contenitore di JSON incollato a mano, uno snippet nel tema e un tag in Google Tag Manager. Il risultato erano nodi duplicati con lo stesso @id e dati divergenti, più uno schema Recipe che dichiarava ingredienti, tempi di cottura e recensioni inesistenti.

Principio fondante

Ogni proprietà emessa deve corrispondere a contenuto realmente presente e visibile in pagina.

Il plugin non genera, stima o completa dati mancanti. Se un valore non è disponibile, la proprietà viene omessa — mai un segnaposto, mai un valore plausibile.

Conseguenza diretta: non esiste alcun modo di dichiarare aggregateRating o Review da questa configurazione, ed è una scelta deliberata. Le valutazioni si raccolgono da recensioni reali; dichiararle a mano viola le linee guida di Google e, verso il consumatore, è una rappresentazione non veritiera. Le proprietà sono nella lista Vocabulary::FORBIDDEN e il validatore le respinge.

Architettura

cm-schema.php              bootstrap, autoloader, update checker
src/
  Plugin.php               hook su wp_head
  Config.php               tre fonti: filtro > file JSON > option
  Vocabulary.php           proprietà ammesse per tipo schema.org
  Validator.php            errori bloccanti e avvisi
  GraphBuilder.php         assembla e deduplica il grafo
  NodeGenerator.php        contratto dei generatori
  Nodes/
    ServiceNode.php        Service + hasOfferCatalog (vetrina)
    PersonNode.php         Person + ImageObject
    FaqNode.php            FAQPage letto dai blocchi
  Admin/
    SettingsPage.php       pagina sotto Impostazioni, export/import, anteprima
assets/
  admin.js                 validazione mentre si compila, righe ripetibili
config/
  site.example.json        configurazione di riferimento
tests/
  test.php                 controlli senza framework, php tests/test.php

Richiede PHP 8.0. Su versioni precedenti il plugin non si avvia e lo dice in bacheca.

Divisione delle responsabilità

Il plugin non genera Organization, WebSite, WebPage o BreadcrumbList: li produce già il plugin SEO installato. Duplicarli significa creare entità parallele con lo stesso @id.

La regola è: un solo proprietario per nodo. Il plugin SEO possiede i nodi site-wide, questo plugin possiede i nodi di dominio, e si collegano via @id.

Configurazione

Tre fonti, in ordine di precedenza:

1. filtro cm_schema_config — codice, vince sempre
2. config/site.json — versionabile in Git
3. option cm_schema_config — interfaccia amministrativa

Stesso formato in tutti e tre i casi. Su un sito gestito da sviluppatore la configurazione sta in Git; dove interviene anche il cliente sta nella UI.

Vedere config/site.example.json.

L'interfaccia sta in Impostazioni → Dati strutturati: campi strutturati, nessuna area di testo per JSON-LD arbitrario. Da lì si esporta la configurazione in JSON, la si mette in Git e la si reimporta altrove. Quando config/site.json esiste, la pagina lo dice: quel file vince, e quanto salvato da interfaccia resta inerte.

Validazione

Validator restituisce errori bloccanti e avvisi. Va eseguito prima del salvataggio nell'interfaccia. Controlla:

• proprietà non appartenenti al tipo dichiarato (Vocabulary)
• proprietà vietate (aggregateRating, review)
• riferimenti @id a nodi non dichiarati
• pagine non pubblicate referenziate in configurazione
• formato degli @id

Il controllo sul vocabolario intercetta l'errore più comune: usare su un tipo una proprietà che appartiene a un ramo diverso della gerarchia. MenuItem discende da Intangible, non da CreativeWork, quindi non accetta keywords, creator o offeredBy.

Stato

Versione 0.1.0 — modulo vetrina funzionante: Service, Person, FAQPage generati da configurazione, più l'interfaccia amministrativa con anteprima del JSON-LD prima di salvare.

Da fare: moduli ecommerce e news, e scaricare plugin-update-checker in lib/ perché gli aggiornamenti automatici entrino in funzione.

Vedere CLAUDE.md per il piano di lavoro.