SOQVER Forrás előkészítése
Magyar

Blog · Útmutató ·

A so4ag.json fájl és a JSON-LD kiszolgálása Next.js, Astro és Nuxt környezetben

Tudja meg, hová helyezze a so4ag.json fájlt Next.js, Astro és Nuxt környezetben, hogyan ellenőrizze a CI-folyamatban, és hogyan ágyazza be ugyanezeket az adatokat JSON-LD formátumban.

Tárolja az ügyfél üzleti tényeit a webhely tartalma mellett

A SO4AG (Source Objects for AGents) az üzleti tények nyílt formátuma. A 0.1 verzió munkatervezet. A forrásfájlt egyszerű JSON-fájlként tárolhatja a kódtárban, és a következő címen szolgálhatja ki: /so4ag.json. Ugyanezeket a tényeket JSON-LD formátumban is közzéteheti a nyilvános „Tények és feltételek” oldalon.

Ha a fájlt a webhely tartalma mellett tárolja, egy ár vagy szabály módosítását az azt közlő oldallal együtt tekintheti át. Az ellenőrzést végzők látják, mi változott, kire vonatkozik a tény, hol közli az ügyfél és mikor jár le az érvényessége. A forrásfájl ellenőrzését a build kötelező lépésévé is teheti, így a hibás formátumú tények még a közzététel előtt megállítják a buildet. A közzétett tényeket olvasó program kisebb eséllyel hibázik, mert a feltételeket és a dátumokat is látja.

Kezdje egyetlen állítással

Az Example Plumbing példájában a kiszállással végzett szolgáltatás óradíja 95.00 USD. A scope adja meg, mire vonatkozik az ár. Minden állításhoz szükséges a valid_from és a valid_until. A known jelölésű állításhoz legalább egy olyan bizonyíték is kell, amelyhez tartozik egy url és egy observed_at időbélyeg. A példában a bizonyíték az árakat közlő oldalra mutat, és rögzíti, mikor szerepelt ott az ár.

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

Ez a blokk egyetlen állítást tartalmaz. A specifikáció bemutatja, hogyan illeszkednek az állítások a teljes forrásfájlba. SO4AG 0.1 specifikáció

A forrásfájl kiszolgálási címe /so4ag.json

A public/so4ag.json útvonal mindhárom keretrendszerben működik. Ha útvonalat vagy végpontot használ, azt a forrásfájlt ellenőrizze, amelyből a válasz készül. Az URL kiszolgálásához egyetlen útvonalat használjon.

Next.js

Helyezze a fájlt a public/so4ag.json útvonalra, hogy a webhely gyökérkönyvtárából legyen elérhető. Ha az App Routeren keresztül szeretné kiszolgálni, használja a app/so4ag.json/route.ts útvonalat, és az útvonalkezelőből a Response.json(...) segítségével adja vissza a forrásadatokat.

Astro

Helyezze a fájlt a public/so4ag.json útvonalra, vagy hozzon létre statikus végpontot a src/pages/so4ag.json.ts útvonalon a /so4ag.json előállításához. Ha végpontot használ, az általa beolvasott JSON-fájlt tárolja a kódtárban, hogy a build előtt át tudja nézni és ellenőrizni tudja.

Nuxt

Helyezze a fájlt a public/so4ag.json útvonalra. A Nuxt a public/ alatt tárolt fájlokat a webhely gyökeréből szolgálja ki, így az URL a következő lesz: /so4ag.json.

Adja hozzá ezt a hivatkozást az olvasóknak szánt oldalak head részéhez, hogy mindegyik oldal a forrásfájlra mutasson.

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

A fájl ellenőrzése és a JSON-LD előállítása

Futtassa az ellenőrzőprogramot a webhely buildje előtt vagy a CI kötelező lépéseként. Ezek a parancsok a public/ elrendezést használják. Ha egy végpont másik útvonalról olvassa be a JSON-fájlt, azt az útvonalat adja meg az ellenőrzőprogramnak.

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

A parancs a VALID vagy a INVALID kimenetet írja ki. Érvénytelen fájl esetén felsorolja a hibákat és azok helyét. Állítsa be úgy a buildet vagy a CI-feladatot, hogy sikertelen ellenőrzés esetén leálljon. A jelzett helyeken javítsa a forrásfájlt, mielőtt előállítja az oldal kimenetét.

A SO4AG kódtár klónozott példányából futtassa az alábbi konvertert úgy, hogy a so4ag.json az aktuális könyvtárban legyen. Megadhatja a webhely kódtárában lévő ellenőrzött fájl útvonalát is. SO4AG-forráskód

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

Illessze a facts.jsonld tartalmát egy <script type="application/ld+json"> elembe a „Tények és feltételek” oldalon. A szkript tartalmát ugyanabból a fájlból állítsa elő, amelyet a /so4ag.json címen szolgál ki. Így minden frissítés után ugyanazok a tények szerepelnek mindkét kimenetben. Az átalakítás megőrzi a tényeket, valamint a hozzájuk tartozó feltételeket és dátumokat.

Kérje meg az ügyfelet a tények megerősítésére

Ön tartja karban a fájlt és a build során futó ellenőrzéseket. Az ügyfél megerősíti a tényeket, és felelősséget vállal értük. Mielőtt egy tény megjelenik a valid_until címen, kérje meg az ügyfelet, hogy erősítse meg a tény értékét, hatókörét és az alátámasztására szolgáló oldalt. Egy ár például egyszerre legfeljebb 60 napra erősíthető meg.

Miután az ügyfél megerősítette az állítást, frissítse azt és a hozzá tartozó dátumokat, majd futtassa az ellenőrzést, és állítsa elő újra a JSON-LD-t. Az utolsó érvényességi nap után a program korábbi adatként kezeli a tényt. Ha az ügyfél nem közöl egy tényt, a knowledge_state mezőt állítsa unknown értékre, és az állítást érték nélkül tegye közzé. Az oldalakon a „nincs megadva” felirat jelenik meg.

Következő lépés

A fejlesztői útmutató alapján adja hozzá a public/so4ag.json fájlt az ügyfél kódtárához. Ellenőrizze a fájlt a nyilvános ellenőrzőprogrammal, mielőtt az ellenőrzést felveszi a CI-folyamatba.

További cikkek

Útmutató ·

Hogyan tegye közzé vállalkozása adatait egy WordPress-webhelyen?

Telepítse a SO4AG Facts bővítményt a WordPressben, adja meg vállalkozása adatait a feltételekkel és dátumokkal együtt, majd tegye közzé az Adatok és feltételek oldalt, amelyet az adminisztrációs felületen ellenőrizhet.

Útmutató ·

A WooCommerce szállítási, fizetési és visszaküldési feltételeinek rögzítése üzleti adatként

A SO4AG Facts segítségével tekintse át a WooCommerce szállítási és fizetési javaslatait, majd adja meg kézzel a visszaküldési határidőket, a szállítási időket és az egyéb feltételeket.

Útmutató ·

Shopify: adatok és feltételek közzététele alkalmazás nélkül

Tudja meg, hogyan teheti közzé az Adatok és feltételek oldalt a Shopify-on, hogyan adhat hozzá JSON-LD blokkot, és hogyan hivatkozhat a tárhelyen lévő SO4AG-fájlra, ha a fájl nem helyezhető el az áruház domainjének gyökérkönyvtárában.

Ingyenes webhelyaudit Összes cikk