SOQVER Quelle vorbereiten
Deutsch

Leitfaden für Entwickler

SO4AG ist ein offenes Format für geschäftliche Fakten: Jeder Fakt trägt seine Bedeutung, seinen Geltungsbereich, seine Herkunft und seine Gültigkeit. Ein Leser beantwortet eine Frage: Darf dieser Fakt für diese Aufgabe zu diesem Zeitpunkt verwendet werden, und wenn nicht, warum nicht.

Das Format ist kostenlos und benötigt kein Konto. Der Code steht unter der Lizenz Apache-2.0, der Text der Spezifikation unter CC BY 4.0.

Alles an einem Ort

Repository auf GitHub · Spezifikation · JSON Schema · Konformitätssuite · JSON-LD · Validator im Browser · Was funktioniert

Inhalt: 1. Code holen · 2. Eine Quelle validieren · 3. Eine Tatsache abfragen · 4. Eigene Quelle veröffentlichen · 5. API · 6. MCP · 7. Eigener Leser · Jede Branche · Wo Sie das Projekt finden

1. Den Code holen

Sie benötigen Git und Node.js 20 oder neuer. Der Python-Reader benötigt nur die Standardbibliothek (Python 3.10 oder neuer).

git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test

Der letzte Befehl führt die Tests des Referenzcodes gegen die Konformitätssuite aus. Alle sollten bestehen.

In Ihr eigenes Projekt installieren Sie die Pakete jeweils mit einem Befehl:

npm install github:soqvercom/so4ag#v0.1.3
npx so4ag-validate https://example.com/so4ag.json

pip install so4ag
so4ag ask so4ag.json --property refundableDeposit --scope vehicle_class=economy

2. Eine Quelle validieren

Der Validator liest eine Datei oder eine Adresse. Er versteht SO4AG-JSON, die JSON-LD-Form und eine HTML-Seite mit dem JSON-LD darin.

node validator/cli.mjs examples/valid/rental-first-party.json
node validator/cli.mjs https://example.com/so4ag.json
node validator/cli.mjs examples/valid/rental-first-party.json --json

Die Antwort beginnt mit VALID oder INVALID. Bei einer ungültigen Quelle folgt eine Liste der Fehler mit ihrer Stelle in der Datei. Ohne etwas zu installieren funktioniert dasselbe im Validator im Browser.

Eine gültige Quelle belegt nur die korrekte Struktur. Sie sagt nicht, dass der Fakt wahr ist.

3. Fragen, ob ein Sachverhalt verwendet werden darf

Eine Aufgabe gibt an, nach welcher Eigenschaft Sie fragen und für welche Bedingungen (Geltungsbereich). Der Leser gibt jede passende Aussage zurück, dazu die Antwort, ob sie verwendbar ist, und die Gründe, wenn sie es nicht ist.

JavaScript

import { readFileSync } from 'node:fs';
import { validateManifest, selectClaims } from './validator/index.mjs';

const source = JSON.parse(readFileSync('examples/valid/rental-first-party.json', 'utf8'));
const check = validateManifest(source);          // { valid, errors, warnings, stats }

const answers = selectClaims(source, {
  property: 'https://soqver.com/spec/so4ag/0.1/rental#refundableDeposit',
  scope: { branch: 'https://rental.example/branches/prague-airport', vehicle_class: 'economy' },
});
for (const { claim, result } of answers) console.log(claim.id, result.usable, result.reasons, result.value);

Python

python readers/python/so4ag_reader.py ask examples/valid/rental-first-party.json \
  --property refundableDeposit --scope vehicle_class=economy \
  --scope branch=https://rental.example/branches/prague-airport

Probieren Sie dasselbe ohne die Filialbedingung oder zu einem anderen Zeitpunkt (--now 2027-06-01T12:00:00Z, in JavaScript das dritte Argument { now: new Date(…) }). Die Aussage ist dann nicht mehr verwendbar, und der Leser sagt, warum.

GrundWas es bedeutet
expired, not_yet_validDie Aussage gilt zum Zeitpunkt der Frage nicht.
scope_mismatch:<key>Die Aussage gilt für einen anderen Wert der Bedingung, zum Beispiel eine andere Filiale.
scope_not_in_task:<key>Die Aussage ist durch eine Bedingung eingeschränkt, die die Aufgabe nicht nennt. Ohne sie kann niemand sagen, ob die Aussage zutrifft.
unknown, not_applicableDer Herausgeber gibt ausdrücklich an, dass der Wert nicht bekannt ist oder nicht zutrifft. Unbekannt ist nicht null.
disputedDie Aussage ist umstritten.
no_trust_policyDie Aufgabe verlangt eine geprüfte Aussage, nennt aber nicht, wem sie vertraut. Wem zu vertrauen ist, entscheidet derjenige, der die Aussage liest.
attestation_not_authenticatedDie Quelle trägt eine Attestierung mit dem Namen eines Ausstellers, dem Sie vertrauen, Sie haben sie jedoch nicht beim Aussteller authentifiziert. Ein in der Quelle stehender Name ist kein Nachweis.
conflicting_claimsZwei aktuelle Angaben nennen unterschiedliche Werte für denselben Sachverhalt. Der Leser verwendet keine von beiden und bestimmt niemals stillschweigend einen Gewinner.
invalid_sourceDie Quelle bricht die Struktur des Formats (zum Beispiel eine Angabe ohne Nachweis oder ein unlesbares Datum). Nichts davon wird verwendet.
unsupported_versionDie Quelle liegt in einer Version des Formats vor, die der Leser nicht kennt. Sie wird nicht nach den Regeln einer anderen Version gelesen.

Die vollständige Liste der Gründe und Regeln steht in der Spezifikation.

4. Eigene Quelle veröffentlichen

Eine Quelle ist eine JSON-Datei. Die kleinste brauchbare Form hat einen Herausgeber und eine Aussage:

{
  "so4ag": "0.1-draft",
  "id": "https://rental.example/so4ag.json",
  "revision": "2026-11-20.1",
  "published_at": "2026-11-19T20:05:00Z",
  "publisher": {
    "id": "https://rental.example/#org",
    "name": "Example Rental",
    "role": "first_party",
    "domain": "rental.example"
  },
  "profiles": ["https://soqver.com/spec/so4ag/0.1/rental"],
  "subjects": [
    { "id": "https://rental.example/#org", "type": "AutoRental", "name": "Example Rental" },
    { "id": "https://rental.example/branches/prague-airport", "type": "Place", "name": "Prague Airport" }
  ],
  "claims": [
    {
      "id": "https://rental.example/claims/deposit-economy-airport",
      "revision": "3",
      "subject": "https://rental.example/#org",
      "property": "https://soqver.com/spec/so4ag/0.1/rental#refundableDeposit",
      "knowledge_state": "known",
      "value": { "type": "money", "amount": "10000.00", "currency": "CZK" },
      "scope": { "branch": "https://rental.example/branches/prague-airport", "vehicle_class": "economy" },
      "assertion_basis": "publisher_asserted",
      "evidence": [
        { "url": "https://rental.example/terms#deposit", "observed_at": "2026-11-19T20:00:00Z", "kind": "webpage" }
      ],
      "valid_from": "2026-11-20T00:00:00Z",
      "valid_until": "2026-12-20T00:00:00Z"
    }
  ]
}
  1. Speichern Sie die Datei als so4ag.json und prüfen Sie sie mit dem Validator (Schritt 2).
  2. Stellen Sie sie über HTTPS auf Ihrer Domain unter /so4ag.json mit dem Typ application/json bereit.
  3. Fügen Sie den Seiten für Menschen einen Link zur Quelle hinzu:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Um dieselben Fakten in der Seite zu haben, konvertieren Sie die Quelle in JSON-LD und setzen Sie das Ergebnis in ein <script type="application/ld+json">-Tag. Die Konvertierung ist verlustfrei.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Geben Sie jeder Aussage ein Gültigkeitsende (valid_until) und bestätigen oder ändern Sie die Aussage, bevor es verstreicht. Danach verwenden Leser sie nicht mehr.

Jede Branche: das Profil General und Ihr eigenes Profil

Das Format ist an keine Branche gebunden. Eigenschaften (was eine Tatsache bedeutet, ihr Typ und ihre Einheit sowie welche Bedingungen sie einschränken) legt ein Profil fest, und eine Quelle kann mehrere Profile gemeinsam verwenden.

ProfilFür wen
GeneralJedes Unternehmen oder jede Organisation: Betreiber, Standorte und Öffnungszeiten, Kontakte, Sprachen, Angebot und Preis, Zahlung, Buchung, Antwort- und Lieferzeiten, Stornierung, Garantie, Barrierefreiheit, Lizenzen, Verfügbarkeit. 26 Eigenschaften.
Fahrzeugvermietung, EinzelhandelWas branchenspezifisch ist: Kaution, Kilometerbegrenzung, Versand, Rückgabe.
EigenesAlles Weitere. Ein Profil ist eine JSON-Datei auf Ihrer Domain; Sie fragen niemanden und registrieren nichts.

Ihr eigenes Profil beschreibt Ihre Eigenschaften genauso wie unsere: Bezeichnung, Beschreibung, Werttyp, Einheiten, zulässige Codes und Bedingungen. Die kleinste Form:

{
  "id": "https://dental.example/so4ag-profile",
  "name": "Example Dental profile",
  "version": "1",
  "namespace": "https://dental.example/so4ag-profile#",
  "scope_keys": { "day_type": "weekday, weekend, public_holiday, any" },
  "properties": {
    "emergencySlot": {
      "label": { "en": "Same-day treatment of acute pain" },
      "value_types": ["boolean"],
      "required_scope": ["day_type"],
      "max_validity": "P90D",
      "description": "Whether a patient with acute pain is treated on the day of the call."
    }
  }
}
  1. Stellen Sie die Datei per HTTPS unter der in id angegebenen Adresse bereit und fügen Sie diese Adresse in Ihrer Quelle zu profiles hinzu.
  2. Schreiben Sie die Eigenschaft einer Aussage als namespace + Name, also https://dental.example/so4ag-profile#emergencySlot.
  3. Prüfen Sie Profil und Quelle:
    node validator/cli.mjs --check-profile examples/profiles/dental-example-profile.json
    node validator/cli.mjs examples/valid/general-dental.json --profile examples/profiles/dental-example-profile.json

Ein Leser, der Ihr Profil nicht kennt, verwendet die Aussage dennoch, wenn die Aufgabe ihre Bedingungen angibt; gibt die Aufgabe sie nicht an, wird die Aussage nicht verwendet. Die Sicherheitsregeln des Formats gelten daher für jedes Profil gleich. Ein vollständiges Beispiel einer Zahnarztpraxis mit dem Profil General und einem eigenen Profil liegt im Repository: general-dental.json. Schema eines Profils: profile.schema.json.

Sie schreiben die Datei lieber nicht von Hand? Der Dienst SOQVER erstellt aus Ihrer Website einen Vorschlag, Sie bestätigen die Fakten und veröffentlichen die Quelle bei uns oder laden sie für Ihre eigene Domain herunter: Quelle vorbereiten.

5. Veröffentlichte Quellen über die API lesen

Die Oberfläche ist schreibgeschützt und benötigt weder ein Konto noch einen Schlüssel.

curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"

Die erste Adresse liefert die Liste der Quellen, die ein Unternehmen veröffentlicht oder bestätigt hat. Die zweite bewertet die Aussagen einer Quelle für Ihre Aufgabe und gibt für jede usable und reasons zurück. Jede Quelle ist außerdem eine Seite für Menschen (/s/<slug>/), eine Datei /s/<slug>/so4ag.json und eine JSON-LD-Form /s/<slug>/facts.jsonld.

6. Einen Agenten über MCP anbinden

Der MCP-Server ist schreibgeschützt, benötigt kein Konto und verwendet den Transport Streamable HTTP. Im offiziellen MCP Registry ist er als com.soqver/so4ag eingetragen.

https://soqver.com/mcp
WerkzeugFunktion
list_sourcesListet die veröffentlichten Quellen auf.
get_sourceGibt die vollständige Quelle eines Unternehmens zurück.
get_claimsBewertet die Aussagen einer Quelle für eine gegebene Eigenschaft und gegebene Bedingungen.
check_claimGibt an, ob eine Aussage jetzt verwendet werden darf und warum nicht.

Geben Sie in einem Client, der entfernte MCP-Server unterstützt, die obige Adresse ein. Die Antwort des Servers können Sie auch über die Befehlszeile prüfen:

curl -s https://soqver.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

7. Eigenen Reader schreiben

Die Konformitätssuite ist reines JSON und benötigt keinen Code von uns. Sie enthält zwei gültige Quellen in drei Formen, die erwarteten Digests der Angaben, 45 Evaluierungsfälle, 31 Validierungsfälle, 10 Fälle für die gesamte Quelle und 25 Vektoren der kanonischen Form (RFC 8785).

python readers/python/so4ag_reader.py conformance spec/conformance/0.1

Wann ein Reader oder ein Validator die Suite besteht, steht in der Beschreibung der Konformitätssuite. Der Python-Reader wurde unabhängig vom Referenzcode geschrieben und besteht dieselbe Suite; Sie können ihn als Vorbild verwenden.

Wo das Projekt zu finden ist

OrtWozu es dient
GitHub: soqvercom/so4agCode, Spezifikation, Konformitätssuite und Releases. Hier wird das Format entwickelt.
GitHub DiscussionsDer Ort für die Community: Fragen, Vorschläge und Erfahrungen mit dem Format. Hier antworten wir.
GitHub IssuesFehler in der Spezifikation und im Code, Fälle, die das Format nicht ausdrücken kann.
PyPI: so4agDas Python-Paket: pip install so4ag
ReleasesDas JavaScript-Paket und die Dateien jeder Version: npm install github:soqvercom/so4ag
Zenodo (DOI)Ein dauerhafter Link zu den Releases zum Zitieren in Fachartikeln und in der Dokumentation.
MCP RegistryDer Eintrag unseres MCP-Servers: com.soqver/so4ag
Discord: SOQVER · SO4AGKurze Fragen und ein Gespräch mit anderen, die das Format ausprobieren.
DEV: @soqvercomTechnische Artikel und Anleitungen zum Format.
daily.dev: @soqverLinks zu neuen Artikeln für Entwickler.
X · YouTubeNeuigkeiten zum Format und kurze Demos.

Rückmeldungen und Fehler

Haben Sie einen Sachverhalt gefunden, den das Format nicht ausdrücken kann, oder zwei Reader, die unterschiedlich antworten? Erfassen Sie das als Issue auf GitHub. Melden Sie eine Sicherheitslücke bitte per E-Mail an [email protected].