SOQVER Připravit zdroj
Čeština

Blog · Návod ·

Jak zpřístupnit so4ag.json a JSON-LD v Next.js, Astro a Nuxtu

Zjistěte, kam v Next.js, Astro a Nuxtu umístit soubor so4ag.json, jak ho ověřit v CI a jak stejné údaje vložit na stránku jako JSON-LD.

Uchovávejte údaje klienta vedle obsahu webu

SO4AG (Source Objects for AGents) je otevřený formát pro údaje o firmách. Verze 0.1 je pracovní návrh. Zdrojový soubor můžete uložit do repozitáře jako běžný soubor JSON a zpřístupnit ho na adrese /so4ag.json. Stejné údaje můžete zveřejnit ve formátu JSON-LD na stránce „Fakta a podmínky“.

Když soubor uložíte vedle obsahu webu, můžete změnu ceny nebo pravidel zkontrolovat společně se stránkou, která cenu či pravidla uvádí. Při kontrole je vidět, co se změnilo, koho se údaj týká, kde ho klient uvádí a kdy končí jeho platnost. Ověření souboru můžete také nastavit jako povinnou součást sestavení webu, aby údaje v chybném formátu sestavení zastavily ještě před zveřejněním. Program, který zveřejněné údaje čte, má menší prostor pro chybu, protože má k dispozici jejich podmínky a data platnosti.

Začněte jedním tvrzením

V příkladu firmy Example Plumbing stojí servisní výjezd 95.00 USD za hodinu. Pole scope určuje, na co se cena vztahuje. Každé tvrzení musí obsahovat valid_from a valid_until. Tvrzení označené jako known musí obsahovat také alespoň jeden doklad s adresou url a časovým údajem observed_at. V tomto příkladu doklad odkazuje na stránku s ceníkem a zaznamenává, kdy tam byla cena zjištěna.

{
  "id": "https://plumbing.example/so4ag.json#price-hour",
  "subject": "https://plumbing.example/#org",
  "property": "https://soqver.cz/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 obsahuje jedno tvrzení. Ve specifikaci najdete, jak se tvrzení zapisují do úplného zdrojového souboru. Specifikace SO4AG 0.1

Zpřístupněte zdrojový soubor na adrese /so4ag.json

Cesta public/so4ag.json funguje ve všech třech frameworcích. Pokud použijete trasu nebo koncový bod, ověřte zdrojový soubor, ze kterého se vytváří odpověď. Pro tuto adresu URL použijte jen jeden způsob zpřístupnění.

Next.js

Uložte soubor jako public/so4ag.json. Tím ho zpřístupníte z kořene webu. Pokud ho chcete zpřístupnit pomocí App Routeru, použijte app/so4ag.json/route.ts a ve funkci obsluhující trasu vraťte zdrojová data pomocí Response.json(...).

Astro

Uložte soubor jako public/so4ag.json nebo vytvořte statický koncový bod v src/pages/so4ag.json.ts, který při sestavení vytvoří /so4ag.json. Pokud použijete koncový bod, uložte soubor JSON, ze kterého čte, do repozitáře, abyste ho mohli před sestavením zkontrolovat a ověřit.

Nuxt

Uložte soubor jako public/so4ag.json. Nuxt zpřístupňuje soubory z adresáře public/ přímo z kořene webu, takže soubor najdete na adrese /so4ag.json.

Do části <head> stránek, které návštěvníci čtou, přidejte následující odkaz. Každá stránka tak bude odkazovat na zdrojový soubor.

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

Ověřte soubor a vygenerujte JSON-LD

Spusťte validátor před sestavením webu nebo jako povinný krok v CI. Následující příkazy počítají se souborem v adresáři public/. Pokud koncový bod čte soubor JSON z jiného umístění, předejte validátoru příslušnou cestu.

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

Příkaz vypíše VALID nebo INVALID. Pokud soubor ověřením neprojde, vypíše chyby a místa, kde se vyskytují. Nastavte sestavení nebo úlohu v CI tak, aby se při neúspěšném ověření zastavily. Podle vypsaných míst opravte zdrojový soubor, než vygenerujete výstup stránky.

V klonu repozitáře SO4AG spusťte následující příkaz pro převod se souborem so4ag.json v aktuálním adresáři. Můžete také zadat cestu k ověřenému souboru v repozitáři svého webu. Zdrojový kód SO4AG

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

Na stránce „Fakta a podmínky“ vložte obsah souboru facts.jsonld dovnitř elementu <script type="application/ld+json">. Obsah elementu generujte ze stejného souboru, který zpřístupňujete na adrese /so4ag.json, aby oba výstupy po každé aktualizaci obsahovaly stejné údaje. Převod zachovává údaje včetně jejich podmínek a dat platnosti.

Požádejte klienta o potvrzení údajů

Vy spravujete soubor a kontroly při sestavení. Klient údaje potvrzuje a odpovídá za ně. Než uplyne platnost údaje podle valid_until, požádejte klienta, aby potvrdil jeho hodnotu, rozsah platnosti a stránku, která ho dokládá. Například cenu lze pokaždé potvrdit nejvýše na 60 dní.

Jakmile klient údaj potvrdí, aktualizujte tvrzení a jeho data platnosti, spusťte ověření a znovu vygenerujte JSON-LD. Jakmile poslední den platnosti uplyne, program údaj považuje za historický. Pokud klient údaj neuvádí, zveřejněte tvrzení s položkou knowledge_state nastavenou na unknown a bez hodnoty. Na stránkách se zobrazí jako „neuvedeno“.

Další krok

Podle příručky pro vývojáře přidejte public/so4ag.json do repozitáře klienta. Než kontrolu přidáte do CI, ověřte soubor ve veřejném validátoru.

Další články

Návod ·

Jak zveřejnit údaje o firmě na webu ve WordPressu

Nainstalujte SO4AG Facts do WordPressu, přidejte údaje o firmě s podmínkami a daty platnosti a zveřejněte stránku Fakta a podmínky, kterou můžete zkontrolovat v administraci.

Návod ·

Jak zveřejnit údaje z WooCommerce o dopravě, platbách a vracení zboží

V SO4AG Facts zkontrolujte návrhy údajů o dopravě a platbách z WooCommerce a ručně doplňte lhůty pro vrácení zboží, dodací lhůty a další podmínky.

Návod ·

Shopify: Jak zveřejnit údaje a podmínky bez aplikace

Zjistěte, jak v Shopify zveřejnit stránku Fakta a podmínky, přidat JSON-LD a odkázat na hostovaný soubor SO4AG, když ho nelze umístit do kořene domény obchodu.

Bezplatný audit webu Všechny články