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.