Blog · Guida ·
Come servire so4ag.json e JSON-LD con Next.js, Astro e Nuxt
Dove inserire so4ag.json in Next.js, Astro e Nuxt, come convalidarlo in CI e come incorporare gli stessi dati in formato JSON-LD.
Tenga i dati del cliente accanto ai contenuti
SO4AG (Source Objects for AGents) è un formato aperto per i dati aziendali. La versione 0.1 è una bozza di lavoro. Può conservare la fonte come file JSON nel repository e renderla disponibile all’indirizzo /so4ag.json. Gli stessi dati possono comparire in formato JSON-LD su una pagina pubblica «Dati e condizioni».
Conservare il file accanto ai contenuti del sito consente di esaminare le modifiche a un prezzo o a una condizione insieme alla pagina che li riporta. Chi esegue la revisione può vedere che cosa è cambiato, a chi si applica il dato, dove lo dichiara il cliente e quando scade. Può anche rendere obbligatoria la validazione durante la build, in modo che dati malformati blocchino la build prima della pubblicazione. Un programma che legge i dati pubblicati ha meno probabilità di interpretarli male, perché può leggerne le condizioni e le date.
Parta da una dichiarazione
Un esempio di Example Plumbing riporta un prezzo di 95.00 USD all’ora per un intervento. Il campo scope indica a che cosa si applica il prezzo. Ogni dichiarazione richiede valid_from e valid_until. Una dichiarazione contrassegnata come known richiede inoltre almeno un elemento di riscontro con un campo url e una marca temporale observed_at. In questo esempio, il riscontro rimanda alla pagina dei prezzi e registra quando vi è stato rilevato il prezzo.
{
"id": "https://plumbing.example/so4ag.json#price-hour",
"subject": "https://plumbing.example/#org",
"property": "https://soqver.com/spec/so4ag/0.1/general#price",
"knowledge_state": "known",
"value": {
"type": "money",
"amount": "95.00",
"currency": "USD"
},
"scope": {
"item": "service call",
"per": "hour"
},
"assertion_basis": "publisher_asserted",
"evidence": [
{
"url": "https://plumbing.example/prices",
"observed_at": "2026-11-20T15:00:00Z",
"kind": "webpage"
}
],
"valid_from": "2026-11-20T00:00:00Z",
"valid_until": "2027-01-15T00:00:00Z"
}
Questo blocco contiene una dichiarazione. Consulti la specifica per vedere come si inseriscono le dichiarazioni nel file sorgente completo. Specifica SO4AG 0.1
Renda disponibile il file sorgente all’indirizzo /so4ag.json
Il percorso public/so4ag.json funziona in tutti e tre i framework. Se usa una route o un endpoint, esegua la validazione sul file sorgente da cui provengono i dati della risposta. Usi un solo percorso per servire il file a quell’URL.
Next.js
Collochi il file in public/so4ag.json per renderlo disponibile dalla radice del sito. Se preferisce servirlo tramite App Router, usi app/so4ag.json/route.ts e faccia restituire al gestore della route i dati sorgente con Response.json(...).
Astro
Collochi il file in public/so4ag.json oppure crei un endpoint statico in src/pages/so4ag.json.ts per generare /so4ag.json. Se usa l’endpoint, conservi nel repository il JSON che l’endpoint legge, così potrà esaminarlo e validarlo prima della build.
Nuxt
Collochi il file in public/so4ag.json. Nuxt rende disponibili dalla radice del sito i file in public/, quindi l’URL è /so4ag.json.
Aggiunga questo link alla sezione head delle pagine consultate dagli utenti, in modo che ciascuna rimandi al file sorgente.
<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
Validi il file e generi il JSON-LD
Esegua il validatore prima della build del sito o come passaggio obbligatorio della CI. Questi comandi usano la struttura public/. Se un endpoint legge il JSON da un altro percorso, passi quel percorso al validatore.
npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json
Il comando restituisce VALID oppure INVALID. Se il file non è valido, elenca gli errori e indica dove si trovano. Configuri la build o il job di CI in modo che si interrompa se la validazione non riesce. Usi le posizioni indicate per correggere il file sorgente prima di generare l’output della pagina.
Da un clone del repository SO4AG, esegua il convertitore qui sotto con so4ag.json nella directory corrente. Può anche passare il percorso del file validato nel repository del suo sito. Codice sorgente di SO4AG
node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
Inserisca il contenuto di facts.jsonld in un tag <script type="application/ld+json"> nella pagina «Dati e condizioni». Generi il contenuto dello script dallo stesso file che rende disponibile all’indirizzo /so4ag.json, così entrambe le versioni riporteranno gli stessi dati dopo ogni aggiornamento. La conversione conserva i dati, comprese le relative condizioni e date.
Chieda al cliente di confermare i dati
Lei si occupa della manutenzione del file e dei controlli di build. Il cliente conferma i dati e ne garantisce l’esattezza. Prima che un dato compaia in valid_until, chieda al cliente di confermarne il valore, l’ambito di applicazione e la pagina di riscontro. Un prezzo, ad esempio, può essere confermato per un massimo di 60 giorni alla volta.
Dopo la conferma del cliente, aggiorni la dichiarazione e le relative date, quindi esegua la validazione e rigeneri il JSON-LD. Trascorso l’ultimo giorno di validità, un programma tratta il dato come storico. Se il cliente non dichiara un dato, pubblichi la dichiarazione impostando knowledge_state su unknown e lasciando il valore assente. Nelle pagine il dato appare come «non dichiarato».
Passaggio successivo
Aggiunga public/so4ag.json al repository del cliente seguendo la guida per sviluppatori. Verifichi il file con il validatore pubblico prima di aggiungere il controllo alla CI.