Come nasce GEO Audit Result, lo schema dati per gli audit GEO

Uno score riassume un esito. Un audit deve spiegare quali segnali lo hanno prodotto.

Quando abbiamo iniziato a costruire il motore di audit GEO di GeoSonar, il problema non era soltanto calcolare un punteggio. Era rappresentare il risultato in modo che fosse validabile, confrontabile, renderizzabile e soprattutto interoperabile: JSONL per i risultati event-like, Parquet per l'analisi colonnare, JSON per il contratto applicativo, CSV per gli export tabellari e PDF per la lettura finale da parte dell'utente.

Lo schema dati GEO Audit Result è un contratto basato su JSON Schema per rappresentare l'output di un audit GEO: punteggi, finding, test di citazione AI, fonti citate, brand competitor, evidenze, raccomandazioni e priorità operative. Serve a rendere un audit di visibilità AI non solo leggibile, ma anche riutilizzabile da dashboard, API, report, export e workflow analitici.

In altri domini esistono già formati, strumenti o convenzioni mature: SARIF per i risultati di analisi statica, Lighthouse per gli audit di qualità delle pagine, Schema.org per descrivere entità web, W3C Web Annotation per annotare risorse.

Per gli audit GEO, invece, non abbiamo trovato un formato operativo equivalente: uno schema pensato per descrivere nello stesso contratto citazioni AI, fonti, brand competitor, evidenze, raccomandazioni e punteggi.

Con i motori generativi la visibilità non dipende più soltanto dal ranking delle pagine. ChatGPT, Perplexity, Gemini, Claude e Copilot sintetizzano risposte, selezionano fonti, associano brand a determinati temi e ne ignorano altri. In molti audit, quindi, la domanda non è più solo "Come siamo posizionati?", ma "Come veniamo percepiti dai sistemi AI, accanto a quali fonti e con quale livello di autorevolezza?".

Un output pensato solo come report non sarebbe bastato. E un JSON costruito soltanto per alimentare una UI era fuori discussione.

Serviva uno schema dati capace di descrivere che cosa rappresenta davvero un audit GEO: punteggi, evidenze, fonti, competitor, citazioni, raccomandazioni e relazioni tra questi elementi.

Questo articolo racconta come è nata questa scelta architetturale, quali standard sono stati analizzati, quali limiti emergevano dai modelli esistenti e perché il risultato finale non è soltanto uno schema JSON, ma un modo preciso di rappresentare un audit GEO per i motori generativi.

L’idea di fondo è semplice:

• il punteggio sintetizza un risultato, ma non spiega perché un brand sia visibile, o invisibile, nelle risposte AI
• lo schema dati collega score, finding, evidenze, fonti, competitor e raccomandazioni in una struttura coerente
• il modello dell’audit permette di riusare lo stesso risultato in report, dashboard, API, export e analisi storiche
• la distinzione tra artifact e fragment riduce l’ambiguità su dove una issue compare realmente.

La genesi dello schema GEO tra SARIF, RFC, JSON Schema e Lighthouse

Il punto di partenza era semplice: esiste già uno standard per rappresentare un audit SEO, GEO o di visibilità nei motori AI?

Nel perimetro che ci serviva, la risposta era no.

Gli audit SEO esistono da anni, ma il settore è frammentato. Semrush, Ahrefs, Screaming Frog, Lighthouse, Search Console e decine di tool proprietari usano strutture diverse: export CSV, payload API, dashboard interne, JSON tecnici. Esistono convenzioni ricorrenti, ma non un modello condiviso.

Nel mondo GEO la situazione è ancora più immatura. La letteratura e i benchmark che abbiamo analizzato descrivono metriche, dataset, ranking sperimentali e metodologie di valutazione, ma non un formato operativo capace di rappresentare nello stesso schema citazioni AI, fonti, competitor, evidenze, punteggi e raccomandazioni.

Questo ha chiarito subito un punto: non aveva senso cercare uno standard GEO già pronto da adottare. Serviva un modello specializzato per questo dominio.

Reinventare la ruota sarebbe stato il modo peggiore di partire

La scelta, però, non è stata reinventare tutto da zero. Al contrario: riusare strutture già mature per problemi specifici e adattarle al contesto GEO.

• SARIF offriva un modello robusto per regole, finding, severità e localizzazione delle issue.
• Lighthouse mostrava una struttura chiara per categorie, audit e punteggi normalizzati.
• Schema.org forniva un lessico consolidato per entità web, URL, organizzazioni e identificatori pubblici.
• JSON Schema e OpenAPI risolvevano il problema della validazione, del versionamento e dell’interoperabilità.
• W3C Web Annotation e RFC 3986 aiutavano a rappresentare correttamente risorse, frammenti e selettori.
• Infine, i pattern usati nei vulnerability scanner e nei sistemi di analisi statica chiarivano la distinzione tra regola, issue e occorrenza concreta.

La conclusione è stata quasi inevitabile: GEO Audit Result non doveva essere uno standard generico, ma una specializzazione di dominio costruita sopra standard già consolidati.

Lo score riassume il risultato. Lo schema deve spiegare da dove nasce.

L’audit GEO come risultato strutturato

La prima versione dello schema aveva un obiettivo molto preciso: definire una struttura stabile per rappresentare il risultato di un audit GEO.

Da SARIF abbiamo preso diversi concetti strutturali:

• tool, per identificare il sistema che ha generato l’audit
• run, per rappresentare una specifica esecuzione
• findings, per descrivere le issue emerse durante l’analisi
• campi come ruleId, severity, message e recommendation, per dare ai finding una struttura leggibile, classificabile e automatizzabile

Da Lighthouse è arrivata soprattutto la grammatica del punteggio:

• scores, come livello aggregato
• categories, come raggruppamento dei pilastri
• audits, come unità atomica di valutazione
• campi come score, displayValue, scoreDisplayMode e details, per distinguere tra metriche numeriche, controlli binari, informazioni diagnostiche e dati non applicabili

Questo approccio ha evitato due errori opposti.

Il primo sarebbe stato costruire un report puramente narrativo, leggibile da un essere umano ma difficile da validare, confrontare e versionare nel tempo.

Il secondo sarebbe stato adottare un modello troppo vicino all’analisi statica del codice, efficace per rappresentare finding tecnici ma inadatto a descrivere un brand, una citazione AI, una fonte autorevole o una raccomandazione editoriale.

SARIF forniva rigore strutturale. Lighthouse offriva una grammatica chiara per score, categorie e controlli. Il dominio GEO richiedeva però un ulteriore livello: rappresentare dati specifici della visibilità nei motori generativi.

Il passaggio decisivo è stato questo: il risultato dell’audit non doveva più essere soltanto un report finale da leggere. Doveva diventare una struttura dati utilizzabile lungo tutto il ciclo di vita dell’audit.

Dalla struttura generica ai dati della visibilità AI

Il passaggio successivo è arrivato dal confronto tra lo schema iniziale e il modello usato da GeoSonar.

La prima versione dello schema era forte sul piano strutturale: finding tipizzati, categorie, audit, punteggi normalizzati e validazione. Mancava però una parte fondamentale specializzata e tipizzata: i dati reali osservati negli audit GEO. Citation test, competitor presenti nelle risposte AI, segnali di autorevolezza, crawler AI, presenza social, relazioni tra SERP e visibilità generativa, blueprint e priorità operative.

La scelta più utile non è stata sostituire il modello iniziale, ma integrarlo con i dati specifici del dominio GEO.

La versione successiva dello schema ha mantenuto la struttura SARIF/Lighthouse-oriented e ha assorbito i concetti nativi di GeoSonar:

• citationTests, per verificare se un brand viene citato dai motori AI
• citationNetwork, per rappresentare quali domini vengono citati da quali motori
• competingBrands, per i brand che appaiono nelle risposte al posto del target
• geoMethods, per modellare le tecniche GEO derivate dalla ricerca accademica
• serpImpact, per collegare posizione SERP e potenziale impatto GEO
• socialPresence, per la verifica delle piattaforme social e review
• crawlerAccess, per l'accessibilità ai crawler AI
• platformReadiness, per misurare la preparazione per singoli ambienti
• actionPlan, per trasformare il risultato in priorità operative
• executiveSummary, per mantenere una sintesi leggibile
• citationGraphMetrics, per aprire il modello a metriche di rete

È qui che lo schema ha smesso di essere solo una struttura formale ed è diventato la rappresentazione canonica dell’audit GEO.

Il caso location: quando una parola crea rumore

Uno dei passaggi più significativi ha riguardato l'analisi di un termine apparentemente neutro e innoquo: location.

Nel mondo SARIF, location funziona bene. Un linter trova un problema in un file, a una riga, a una colonna. Il concetto è preciso. Nel mondo Web e GEO, invece, location diventa ambiguo. Può indicare una posizione geografica, un URL, una sezione della pagina o un artefatto tecnico specifico come robots.txt, llms.txt, una sitemap, un blocco JSON-LD, una meta description o una pagina pricing.

Ma potrebbe andare peggio. Potrebbe piovere.

Molto peggio: nelle raccomandazioni generate da LLM, location, soprattutto quando compariva accanto alla sigla GEO, rischiava di essere interpretato come luogo geografico invece che come punto del sito su cui intervenire.

Ancora oggi, quando facciamo test di citazione su GeoSonar, capita di vedere risultati che scivolano verso GIS, geolocation o perfino "Georadar" (strumenti di prospezione usati in archeologia e ingegneria civile per capire cosa c'è sotto terra).

Si tratta di un errore paradossale ma emblematico: in assenza di un contesto univoco, i modelli linguistici tendono a risolvere l'ambiguità seguendo l'associazione semantica più frequente.

La soluzione non è stata cercare un sinonimo, ma identificare il concetto corretto all'interno degli standard esistenti. location non descriveva abbastanza precisamente il punto in cui compare l'occorrenza di una issue. Mentre fragment era più aderente sul piano concettuale e riduceva un'ambiguità che faceva deragliare facilmente gli LLM.

Il modello è diventato:

flowchart TD
    A[Finding] --> B[occurrences]
    B --> C[artifact]
    C --> D[name]
    C --> E[fragment]

In altre parole: un finding può avere una o più occorrenze. Ogni occorrenza appare in un artefatto. L'artefatto può essere una pagina, un file tecnico, un blocco strutturato o un punto specifico del sito. Un file tecnico può essere, ad esempio, llms.txt, robots.txt, una sitemap o un feed. Un punto specifico del sito può essere una pagina pricing, una sezione FAQ, una pagina prodotto o un profilo autore. Il fragment indica la porzione rilevante: una sezione, un meta tag, un blocco JSON-LD, una tabella, un contenuto editoriale, un elemento di prova.

artifact dice dove compare una issue; fragment dice quale parte di quell'artefatto conta davvero.

Questa scelta ha tre vantaggi.

Primo: riduce l'ambiguità semantica. Non si chiede più al modello di "indovinare" il significato di "location".

Secondo: mantiene la compatibilità con la logica SARIF. artifact e fragment sono concetti affini ad artifactLocation e region, ma adattati a documenti Web renderizzati e porzioni semanticamente riconoscibili della pagina, anziché a file sorgente.

Terzo: si allinea con il W3C Web Annotation Data Model, dove una risorsa ha una source e una porzione selezionata tramite selector, e con RFC 3986, dove il fragment identifier rappresenta una parte indirizzabile della risorsa.

Questo è stato il momento in cui il modello è diventato realmente un modello dati, non solo un elenco di campi.

Separare il modello dell’audit dalla sua rappresentazione

Un altro passaggio importante è stato separare la struttura dell’audit dalla logica di rendering del report.

Il modello iniziale funzionava per costruire il report finale, ma rifletteva soprattutto esigenze di presentazione con campi flat come: audit_data, keyword_data, citation_data, social_data, insights, configurazioni, dati grezzi e sezioni aggregate. Era una struttura pensata soprattutto per il rendering della UI e del report finale, non ancora uno schema dati stabile, validabile e riutilizzabile.

La nuova struttura dell' AuditResult ha separato i concetti:

• i punteggi aggregati risiedono in scores;
• i dettagli metrici in categories[].audits[];
• le issue puntuali in findings[];
• le raccomandazioni strategiche in insights[];
• i test di citazione in citationTests;
• i segnali tecnici e di piattaforma risiedono in sezioni dedicate;
• il piano operativo vive in actionPlan.

Questa separazione non era una scelta stilistica. Un audit GEO non deve soltanto essere persistito: deve poter essere validato, renderizzato, trasformato in PDF, interrogato, confrontato nel tempo, esposto via API e riutilizzato in analisi e workflow decisionali anche esterni. Per questo serviva uno schema dati stabile.

Perché lo schema dell’audit viene prima dello stack dati

Attorno allo schema entrano poi anche Polars, DuckDB, Parquet, JSONL e MotherDuck. Sono componenti importanti dell’infrastruttura, ma il loro ruolo riguarda l’elaborazione e l’interrogazione dei dati, non la definizione dell’audit.

Nel contesto del GEO Audit Result diventano rilevanti solo quando aiutano a spiegare una decisione sul modello dell’audit.

Ad esempio, la scelta di tenere un oggetto AuditResult completo ha senso anche se in futuro alcune parti vengono proiettate in Parquet o viste DuckDB per query analitiche. Lo storage può cambiare, ma il modello dell’audit resta stabile.

L’architettura dati usata da GeoSonar per gestire viste analitiche, storage colonnare e serie storiche è approfondita in quest'altro articolo.

Allo stesso modo, il passaggio a viste colonnari non sostituisce lo schema: risolve il problema di interrogare sotto-metriche, KPI e serie storiche senza dover processare ogni volta l'intero documento JSON. Il documento completo resta comunque la rappresentazione canonica del risultato dell’audit.

Il funzionamento del motore di scoring GEO e la costruzione dei punteggi sono trattati separatamente nell’articolo dedicato allo scoring engine.

Il principio architettonico è chiaro: lo schema definisce l'identità di un audit, mentre l'infrastruttura dati ne garantisce l'efficienza operativa.

Parquet, DuckDB, Polars e MotherDuck rispondono a una domanda di efficienza. Lo schema risponde a una domanda diversa: che cosa significa questo audit.

GEO Audit Result v1.0.0: la struttura finale dello schema

La versione attuale di GEO Audit Result è definita come uno schema JSON Schema Draft 2020-12 identificato da un $id versionato:

https://geosonar.ai/schema/geo-audit-result/v1.0.0

I campi obbligatori definiscono il nucleo minimo dello schema:

• $schema;
• version;
• tool;
• run;
• target;
• scores;
• categories.

Il resto estende il risultato verso il dominio GEO:

I tipi interni danno sostanza al contratto: Score, Category, Audit, Finding, Occurrence, Artifact, SourceReference, Insight, CitationTestResult, CitationNetworkEntry, GeoMethodResult, Action e Rule.

Il risultato è uno schema pensato per essere leggibile da un operatore umano, validabile da una macchina, interoperabile con sistemi terzi e riutilizzabile in report, API, frontend e analisi successive.

La specifica del GEO Audit Result nasce dalla consapevolezza che un audit GEO non può esaurirsi in una dashboard.

Una dashboard mostra un punteggio. Uno schema spiega che cosa significa quel punteggio: da quali dati nasce, quali issue lo abbassano, quali motori AI citano il brand, quali fonti sostengono la risposta, quali azioni hanno priorità e quale parte del sito deve essere corretta.

Senza schema, un audit resta difficile da validare, confrontare e riusare. Con uno schema, ogni risultato può diventare input per report, API, dashboard, analisi storiche e workflow editoriali.

La scelta più importante non è stata tecnica in senso stretto, ma metodologica: riconoscere che in un dominio nuovo non occorre inventare tutto da zero, né fingere che gli standard esistenti siano sufficienti. È necessario derivare, specializzare e adattare.

SARIF non conosce il concetto di citazione in ChatGPT. Lighthouse non sa cosa sia un brand ignorato da Perplexity. Schema.org non modella un action plan GEO. Il W3C Web Annotation Model non stabilisce se un sito sia pronto per Gemini o Copilot.

Ma messi insieme, con attenzione, offrono una base solida.

Il GEO Audit Result è nato così: come profilo tecnico interno per descrivere una classe di problemi che negli audit GEO emerge con frequenza crescente.

Poi lo schema è diventato parte dell’audit stesso. Non perché renda il sistema più elegante, ma perché rende il risultato più preciso: questo è il punteggio, questa è l’evidenza, questa è l’occorrenza, questo è l’artefatto, questo è il frammento, questa è l’azione. Have fun!

Il GEO Score misura quanto un sito sia pronto per essere individuato dai motori generativi. Lo schema GEO Audit Result svolge un compito complementare: definisce come narrare, con precisione, perché quel sito sia pronto o perché non lo sia ancora.

Nei risultati generativi, la menzione può pesare quanto, o più, del click:

se un brand viene citato nella risposta, entra nella shortlist mentale dell'utente.
se viene omesso, può sparire dalla valutazione iniziale.

Per questo non basta sapere se un brand compaia nella risposta. Occorre comprendere quale evidenza ne abbia determinato la comparsa, quale mancanza lo abbia escluso e quale intervento possa modificare la successiva risposta generata.

Questo è il ruolo dello schema

rendere la visibilità generativa osservabile, validabile e argomentabile su dati espliciti.

FAQ

Che cos'è il GEO Audit Result?

È uno schema dati per rappresentare il risultato di un audit GEO: punteggi, finding, test di citazione AI, fonti citate, brand competitor, evidenze, raccomandazioni e priorità operative.

Perché non basta una dashboard?

Una dashboard è utile per leggere velocemente un risultato, ma non basta per validarlo, confrontarlo nel tempo, interrogarlo via API o trasformarlo in dataset analitici. Lo schema rende il risultato riutilizzabile e interoperabile.

Perché usare SARIF e Lighthouse come riferimenti?

SARIF offre un modello utile per regole, finding e severità. Lighthouse offre una grammatica familiare per categorie, audit e punteggi. Il GEO Audit Result prende questi concetti e li adatta alla visibilità nei motori generativi.

Che differenza c'è tra artifact e fragment?

artifact indica l'oggetto in cui appare una issue, ad esempio una pagina, una sitemap, robots.txt, llms.txt, un blocco JSON-LD o un profilo autore. fragment indica la parte esatta di quell'oggetto, ad esempio una sezione, un meta tag, una tabella, un paragrafo o uno snippet di evidenza.

Lo schema sostituisce Parquet, DuckDB o Polars?

No. Lo schema definisce che cosa rappresenta un audit GEO. Parquet, DuckDB e Polars risolvono problemi diversi: storage colonnare, interrogazione dei dati e trasformazioni analitiche sul risultato strutturato dell’audit.

Riferimenti tecnici e metodologici

• OASIS SARIF v2.1.0
• Chrome Developers: Lighthouse
• Schema.org
• JSON Schema Draft 2020-12
• OpenAPI Specification
• W3C Web Annotation Data Model
• RFC 3986: Uniform Resource Identifier - Generic Syntax
• RFC 9309: Robots Exclusion Protocol
• Sitemaps.org protocol
• JSON-LD 1.1
• llms.txt proposal
• Wikipedia: Technical standard
• Wikipedia: Request for Comments
• Wikipedia: Database schema
• Wikipedia: Static program analysis
• Wikipedia: Vulnerability scanner
• Polars documentation
• DuckDB documentation
• Apache Parquet documentation
• PostgreSQL documentation: JSON types