SOQVER Pripraviť zdroj
Slovenčina

Blog · Návod ·

Sprístupnenie súboru so4ag.json a bloku JSON-LD v Next.js, Astro a Nuxt

Zistite, kam umiestniť súbor so4ag.json v Next.js, Astro a Nuxt, ako ho overiť v CI a ako vložiť tie isté údaje vo formáte JSON-LD.

Uchovávajte fakty klienta spolu s obsahom webu

SO4AG (Source Objects for AGents) je otvorený formát pre fakty o firme. Verzia 0.1 je pracovný návrh. Zdroj môžete uložiť v repozitári ako obyčajný súbor JSON a sprístupniť ho na adrese /so4ag.json. Tie isté fakty môžete uviesť vo formáte JSON-LD na verejnej stránke „Fakty a podmienky“.

Keď súbor uložíte spolu s obsahom webu, môžete zmenu ceny alebo pravidla skontrolovať zároveň so stránkou, na ktorej je údaj uvedený. Pri kontrole vidno, čo sa zmenilo, na koho sa údaj vzťahuje, kde ho klient uvádza a kedy sa končí jeho platnosť. Validáciu môžete nastaviť ako povinnú súčasť zostavenia, aby chybne zapísané fakty zastavili zostavenie ešte pred zverejnením. Program, ktorý číta zverejnené fakty, má menší priestor na chybu, pretože má k dispozícii ich podmienky aj dátumy.

Začnite jedným tvrdením

Príklad od Example Plumbing uvádza sadzbu 95.00 USD za hodinu pri servisnom výjazde. Položka scope určuje, na čo sa cena vzťahuje. Každé tvrdenie musí obsahovať valid_from a valid_until. Tvrdenie označené ako known musí obsahovať aj aspoň jeden dôkaz s položkou url a časovou pečiatkou observed_at. Dôkaz v tomto príklade odkazuje na stránku s cenníkom a zaznamenáva, kedy tam bola cena zistená.

{
  "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"
}

Tento blok predstavuje jedno tvrdenie. V špecifikácii nájdete, ako sa tvrdenia začleňujú do celého zdrojového súboru. Špecifikácia SO4AG 0.1

Sprístupnite zdroj na adrese /so4ag.json

Cesta public/so4ag.json funguje vo všetkých troch frameworkoch. Ak používate trasu alebo koncový bod, validujte zdrojový súbor, z ktorého sa tvorí odpoveď. Pre danú URL použite jediný spôsob sprístupnenia.

Next.js

Súbor umiestnite na cestu public/so4ag.json, aby bol dostupný z koreňového adresára webu. Ak ho chcete sprístupniť cez App Router, použite app/so4ag.json/route.ts a z obslužnej funkcie trasy vráťte zdrojové údaje pomocou Response.json(...).

Astro

Súbor umiestnite na cestu public/so4ag.json alebo vytvorte statický koncový bod na ceste src/pages/so4ag.json.ts, ktorý pri zostavení vytvorí /so4ag.json. Ak použijete koncový bod, uložte súbor JSON, ktorý načítava, do repozitára, aby ste ho mohli pred zostavením skontrolovať a validovať.

Nuxt

Súbor umiestnite na cestu public/so4ag.json. Nuxt sprístupňuje súbory z public/ v koreňovom adresári webu, takže URL je /so4ag.json.

Pridajte tento odkaz do hlavičky stránok, ktoré čítajú návštevníci, aby každá stránka odkazovala na zdrojový súbor.

<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">

Validujte súbor a vygenerujte JSON-LD

Spustite validátor pred zostavením webu alebo ako povinný krok v CI. Tieto príkazy používajú štruktúru public/. Ak koncový bod načítava JSON z inej cesty, odovzdajte túto cestu validátoru.

npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json

Príkaz vypíše VALID alebo INVALID. Ak je súbor neplatný, vypíše chyby aj ich umiestnenie. Nastavte zostavenie alebo úlohu CI tak, aby sa pri neúspešnej validácii zastavili. Podľa uvedených umiestnení opravte zdroj pred vygenerovaním výstupu stránky.

V klone repozitára SO4AG spustite konvertor uvedený nižšie, pričom so4ag.json musí byť v aktuálnom adresári. Konvertoru môžete odovzdať aj cestu k validovanému súboru v repozitári svojho webu. Zdrojový kód SO4AG

node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld

Vložte obsah facts.jsonld do značky <script type="application/ld+json"> na stránke „Fakty a podmienky“. Obsah skriptu generujte z toho istého súboru, ktorý sprístupňujete na adrese /so4ag.json, aby oba výstupy po každej aktualizácii obsahovali rovnaké fakty. Konverzia zachová fakty vrátane ich podmienok a dátumov.

Požiadajte klienta o potvrdenie faktov

Vy spravujete súbor a kontroly pri zostavení. Klient potvrdzuje fakty a stojí za nimi. Skôr než sa údaj dostane na valid_until, požiadajte klienta, aby potvrdil jeho hodnotu, rozsah platnosti a stránku, ktorá ho dokladá. Napríklad cenu možno naraz potvrdiť najviac na 60 dní.

Keď klient tvrdenie potvrdí, aktualizujte ho aj s jeho dátumami, potom spustite validáciu a znova vygenerujte JSON-LD. Po uplynutí posledného dňa platnosti program považuje údaj za historický. Ak klient údaj neuvádza, zverejnite tvrdenie bez hodnoty a nastavte knowledge_state na unknown. Na stránkach sa zobrazí ako „neuvedené“.

Ďalší krok

Podľa príručky pre vývojárov pridajte public/so4ag.json do repozitára klienta. Pred pridaním kontroly do CI overte súbor pomocou verejného validátora.

Ďalšie články

Návod ·

Ako zverejniť údaje o firme na webe vo WordPress

Nainštalujte SO4AG Facts do WordPress, pridajte údaje o firme s podmienkami a dátumami a zverejnite stránku Údaje a podmienky, ktorú môžete skontrolovať v administrácii.

Návod ·

Ako spracovať dopravu, platby a vrátenie tovaru vo WooCommerce do štruktúrovaných údajov

V SO4AG Facts skontrolujte návrhy údajov o doprave a platbách z WooCommerce a potom ručne doplňte lehoty na vrátenie tovaru, dodacie lehoty a ďalšie podmienky.

Návod ·

Shopify: ako zverejniť údaje a podmienky bez aplikácie

Zistite, ako v Shopify zverejniť stránku Údaje a podmienky, pridať JSON-LD a odkázať na hostovaný súbor SO4AG, ak ho nemôžete umiestniť do koreňového adresára domény obchodu.

Bezplatný audit webu Všetky články