SOQVER Quelle vorbereiten
Deutsch

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.

Weitere Artikel

Anleitung ·

So veröffentlichen Sie Ihre Unternehmensangaben auf einer WordPress-Website

Installieren Sie SO4AG Facts in WordPress, ergänzen Sie Ihre Unternehmensangaben um Bedingungen und Datumsangaben und veröffentlichen Sie eine Seite mit Angaben und Konditionen, die Sie im Adminbereich prüfen können.

Anleitung ·

Versand, Zahlung und Rückgabe in WooCommerce als strukturierte Angaben erfassen

Prüfen Sie mit SO4AG Facts die Vorschläge zu Versand und Zahlung in WooCommerce und ergänzen Sie Rückgabefristen, Lieferzeiten und weitere Konditionen von Hand.

Anleitung ·

Shopify: So veröffentlichen Sie Angaben und Konditionen ohne App

Erfahren Sie, wie Sie in Shopify eine Seite mit Angaben und Konditionen veröffentlichen, JSON-LD hinzufügen und auf eine gehostete SO4AG-Datei verlinken, wenn Sie die Datei nicht im Stammverzeichnis Ihrer Shop-Domain ablegen können.

Kostenloses Website-Audit Alle Artikel