Blog · Ghid ·
Cum să puneți la dispoziție so4ag.json și JSON-LD din Next.js, Astro și Nuxt
Aflați unde să plasați so4ag.json în Next.js, Astro și Nuxt, cum să îl validați în CI și cum să integrați aceleași informații în format JSON-LD.
Păstrați informațiile clientului alături de conținut
SO4AG (Source Objects for AGents) este un format deschis pentru informațiile despre o companie. Versiunea 0.1 este un proiect în lucru. Puteți păstra sursa ca fișier JSON simplu în depozitul de cod și o puteți publica la /so4ag.json. Aceleași informații pot apărea în format JSON-LD pe o pagină publică intitulată „Informații și condiții”.
Dacă păstrați fișierul alături de conținutul site-ului, puteți verifica o modificare de preț sau de politică împreună cu pagina care o prezintă. Cei care verifică modificarea pot vedea ce s-a schimbat, cui i se aplică informația, unde o declară clientul și când expiră. Puteți face validarea obligatorie la compilare, astfel încât informațiile cu format incorect să oprească procesul înainte de publicare. Un program care citește informațiile publicate are mai puține șanse să greșească, deoarece le poate vedea condițiile și datele.
Începeți cu o singură afirmație
Un exemplu de la Example Plumbing indică un tarif de 95.00 USD pe oră pentru o intervenție. Câmpul scope precizează la ce se aplică tariful. Fiecare afirmație necesită valid_from și valid_until. O afirmație marcată cu known necesită și cel puțin o dovadă care să includă url și un marcaj temporal observed_at. În acest exemplu, dovada indică pagina de tarife și consemnează când a fost observat tariful pe acea pagină.
{
"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"
}
Acest bloc conține o singură afirmație. Consultați specificația pentru a vedea cum se încadrează afirmațiile în fișierul sursă complet. Specificația SO4AG 0.1
Publicați sursa la /so4ag.json
Calea public/so4ag.json funcționează în toate cele trei frameworkuri. Dacă folosiți o rută sau un endpoint, validați fișierul sursă care furnizează datele pentru răspuns. Folosiți o singură cale de publicare pentru URL.
Next.js
Plasați fișierul la public/so4ag.json pentru a-l publica la rădăcina site-ului. Dacă preferați să îl publicați prin App Router, folosiți app/so4ag.json/route.ts și returnați datele sursă din handlerul rutei cu Response.json(...).
Astro
Plasați fișierul la public/so4ag.json sau creați un endpoint static la src/pages/so4ag.json.ts pentru a genera /so4ag.json. Dacă folosiți endpointul, păstrați în depozitul de cod fișierul JSON pe care îl citește, pentru a-l putea verifica și valida înainte de compilare.
Nuxt
Plasați fișierul la public/so4ag.json. Nuxt publică fișierele din public/ la rădăcina site-ului, astfel că URL-ul este /so4ag.json.
Adăugați acest link în secțiunea head a paginilor pe care le citesc vizitatorii, astfel încât fiecare pagină să indice fișierul sursă.
<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
Validați fișierul și generați JSON-LD
Rulați validatorul înainte de compilarea site-ului sau ca etapă obligatorie în CI. Aceste comenzi folosesc structura public/. Dacă un endpoint citește fișierul JSON de la altă cale, transmiteți acea cale validatorului.
npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json
Comanda afișează VALID sau INVALID. Dacă fișierul este nevalid, comanda afișează erorile și locul în care apar. Configurați compilarea sau sarcina CI să se oprească dacă validarea eșuează. Folosiți pozițiile indicate pentru a corecta sursa înainte de a genera conținutul paginii.
Dintr-o copie clonată a depozitului SO4AG, rulați convertorul de mai jos cu so4ag.json în directorul curent. Puteți transmite și calea către fișierul validat din depozitul site-ului dumneavoastră. Codul sursă SO4AG
node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
Introduceți conținutul fișierului facts.jsonld într-o etichetă <script type="application/ld+json"> pe pagina „Informații și condiții”. Generați conținutul scriptului din același fișier pe care îl publicați la /so4ag.json, astfel încât ambele versiuni să conțină aceleași informații după fiecare actualizare. Conversia păstrează informațiile, inclusiv condițiile și datele lor.
Cereți clientului să confirme informațiile
Dumneavoastră întrețineți fișierul și verificările de compilare. Clientul confirmă informațiile și și le asumă. Înainte ca o informație să ajungă la valid_until, cereți clientului să confirme valoarea, domeniul de aplicare și pagina care o susține. De exemplu, un preț poate fi confirmat pentru cel mult 60 zile odată.
Actualizați afirmația și datele aferente după ce clientul o confirmă, apoi rulați validarea și regenerați JSON-LD. După ultima zi de valabilitate, un program tratează informația ca fiind istorică. Dacă clientul nu declară o informație, publicați afirmația cu knowledge_state setat la unknown și fără valoare. Paginile o afișează ca „nedeclarată”.
Pasul următor
Adăugați public/so4ag.json în depozitul de cod al clientului dumneavoastră urmând ghidul pentru dezvoltatori. Verificați fișierul cu validatorul public înainte de a adăuga verificarea în CI.