Blog · Anleitung ·
so4ag.json und JSON-LD mit Next.js, Astro und Nuxt bereitstellen
Erfahren Sie, wo Sie so4ag.json in Next.js, Astro und Nuxt ablegen, wie Sie die Datei in CI validieren und dieselben Angaben als JSON-LD einbinden.
Kundenfakten zusammen mit den Website-Inhalten pflegen
SO4AG (Source Objects for AGents) ist ein offenes Format für Unternehmensfakten. Version 0.1 ist ein Arbeitsentwurf. Sie können die Quelldatei als reines JSON in Ihrem Repository ablegen und unter /so4ag.json bereitstellen. Dieselben Fakten können auf einer öffentlichen Seite „Fakten und Konditionen“ als JSON-LD erscheinen.
Wenn die Datei bei den Website-Inhalten liegt, können Sie Änderungen an Preisen oder Richtlinien zusammen mit der Seite prüfen, auf der sie angegeben sind. Bei der Prüfung sehen Sie, was sich geändert hat, für wen die Angabe gilt, wo der Kunde sie veröffentlicht und wann sie abläuft. Sie können die Validierung auch als verpflichtende Build-Prüfung einrichten, damit fehlerhaft formatierte Fakten den Build vor der Veröffentlichung stoppen. Ein Programm, das die veröffentlichten Fakten liest, kann sie seltener falsch interpretieren, weil es die Bedingungen und Datumsangaben erkennen kann.
Beginnen Sie mit einer Aussage
Ein Beispiel von Example Plumbing zeigt für einen Vor-Ort-Einsatz einen Preis von 95.00 USD pro Stunde. scope gibt an, wofür der Preis gilt. Jede Aussage benötigt valid_from und valid_until. Eine mit known gekennzeichnete Aussage benötigt außerdem mindestens einen Beleg mit url und einem Zeitstempel observed_at. Hier verweist der Beleg auf die Preisseite und hält fest, wann der Preis dort erfasst wurde.
{
"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"
}
Dieser Block enthält eine einzelne Aussage. Die Spezifikation zeigt, wie Aussagen in die vollständige Quelldatei eingebunden werden. Spezifikation für SO4AG 0.1
Quelldatei bereitstellen unter /so4ag.json
Der Pfad public/so4ag.json funktioniert in allen drei Frameworks. Wenn Sie eine Route oder einen Endpunkt verwenden, validieren Sie die Quelldatei, aus der die Antwort erzeugt wird. Nutzen Sie für die URL nur einen Bereitstellungsweg.
Next.js
Legen Sie die Datei unter public/so4ag.json ab, um sie im Stammverzeichnis der Website bereitzustellen. Wenn Sie dafür den App Router verwenden möchten, nutzen Sie app/so4ag.json/route.ts und geben Sie die Quelldaten im Route Handler mit Response.json(...) zurück.
Astro
Legen Sie die Datei unter public/so4ag.json ab oder erstellen Sie unter src/pages/so4ag.json.ts einen statischen Endpunkt, der beim Build /so4ag.json erzeugt. Wenn Sie den Endpunkt nutzen, legen Sie das von ihm gelesene JSON im Repository ab, damit Sie es vor dem Build prüfen und validieren können.
Nuxt
Legen Sie die Datei unter public/so4ag.json ab. Nuxt stellt Dateien aus public/ im Stammverzeichnis der Website bereit. Die URL lautet daher /so4ag.json.
Fügen Sie diesen Link in den head-Bereich der Seiten ein, die Besucher lesen, damit jede dieser Seiten auf die Quelldatei verweist.
<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
Datei validieren und JSON-LD erzeugen
Führen Sie den Validator vor dem Build Ihrer Website oder als verpflichtenden CI-Schritt aus. Diese Befehle gehen von der Verzeichnisstruktur public/ aus. Wenn ein Endpunkt das JSON aus einem anderen Pfad liest, übergeben Sie diesen Pfad an den Validator.
npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json
Der Befehl gibt VALID oder INVALID aus. Bei einer ungültigen Datei listet er die Fehler und ihre Positionen auf. Konfigurieren Sie den Build oder den CI-Job so, dass er bei fehlgeschlagener Validierung abbricht. Korrigieren Sie die angegebenen Stellen in der Quelldatei, bevor Sie die Seitenausgabe erzeugen.
Führen Sie den unten gezeigten Konverter aus einem Klon des SO4AG-Repositorys aus. Dabei muss so4ag.json im aktuellen Verzeichnis liegen. Sie können auch den Pfad zur validierten Datei im Repository Ihrer Website übergeben. SO4AG-Quellcode
node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
Fügen Sie den Inhalt von facts.jsonld in ein <script type="application/ld+json">-Tag auf der Seite „Fakten und Konditionen“ ein. Erzeugen Sie den Skriptinhalt aus derselben Datei, die Sie unter /so4ag.json bereitstellen, damit beide Ausgaben nach jeder Aktualisierung dieselben Fakten enthalten. Bei der Umwandlung bleiben die Fakten einschließlich ihrer Bedingungen und Datumsangaben erhalten.
Lassen Sie die Fakten vom Kunden bestätigen
Sie pflegen die Datei und die Build-Prüfungen. Der Kunde bestätigt die Fakten und steht dafür ein. Bevor eine Angabe unter valid_until erscheint, lassen Sie den Kunden ihren Wert, ihren Geltungsbereich und die Seite bestätigen, die sie belegt. Ein Preis lässt sich beispielsweise jeweils für bis zu 60 Tage bestätigen.
Aktualisieren Sie nach der Bestätigung durch den Kunden die Aussage und ihre Datumsangaben. Führen Sie anschließend die Validierung aus und erzeugen Sie das JSON-LD neu. Nach dem letzten Gültigkeitstag behandelt ein Programm die Angabe als historischen Eintrag. Wenn der Kunde keine Angabe macht, veröffentlichen Sie die Aussage ohne Wert und setzen Sie knowledge_state auf unknown. Auf den Seiten erscheint sie als „nicht angegeben“.
Nächster Schritt
Fügen Sie public/so4ag.json mithilfe des Entwicklerleitfadens zum Repository Ihres Kunden hinzu. Prüfen Sie die Datei mit dem öffentlichen Validator, bevor Sie die Prüfung in die CI aufnehmen.