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.
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
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
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.
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.
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 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.
| Grund | Was es bedeutet |
|---|---|
expired, not_yet_valid | Die 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_applicable | Der Herausgeber gibt ausdrücklich an, dass der Wert nicht bekannt ist oder nicht zutrifft. Unbekannt ist nicht null. |
disputed | Die Aussage ist umstritten. |
no_trust_policy | Die Aufgabe verlangt eine geprüfte Aussage, nennt aber nicht, wem sie vertraut. Wem zu vertrauen ist, entscheidet derjenige, der die Aussage liest. |
attestation_not_authenticated | Die 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_claims | Zwei aktuelle Angaben nennen unterschiedliche Werte für denselben Sachverhalt. Der Leser verwendet keine von beiden und bestimmt niemals stillschweigend einen Gewinner. |
invalid_source | Die Quelle bricht die Struktur des Formats (zum Beispiel eine Angabe ohne Nachweis oder ein unlesbares Datum). Nichts davon wird verwendet. |
unsupported_version | Die 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.
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"
}
]
}
so4ag.json und prüfen Sie sie mit dem Validator (Schritt 2)./so4ag.json mit dem Typ application/json bereit.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">-Tag. Die Konvertierung ist verlustfrei. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) und bestätigen oder ändern Sie die Aussage, bevor es verstreicht. Danach verwenden Leser sie nicht mehr.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.
| Profil | Für wen |
|---|---|
| General | Jedes 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, Einzelhandel | Was branchenspezifisch ist: Kaution, Kilometerbegrenzung, Versand, Rückgabe. |
| Eigenes | Alles 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."
}
}
}
id angegebenen Adresse bereit und fügen Sie diese Adresse in Ihrer Quelle zu profiles hinzu.namespace + Name, also https://dental.example/so4ag-profile#emergencySlot.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.jsonEin 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.
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.
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
| Werkzeug | Funktion |
|---|---|
list_sources | Listet die veröffentlichten Quellen auf. |
get_source | Gibt die vollständige Quelle eines Unternehmens zurück. |
get_claims | Bewertet die Aussagen einer Quelle für eine gegebene Eigenschaft und gegebene Bedingungen. |
check_claim | Gibt 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"}'
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.
| Ort | Wozu es dient |
|---|---|
| GitHub: soqvercom/so4ag | Code, Spezifikation, Konformitätssuite und Releases. Hier wird das Format entwickelt. |
| GitHub Discussions | Der Ort für die Community: Fragen, Vorschläge und Erfahrungen mit dem Format. Hier antworten wir. |
| GitHub Issues | Fehler in der Spezifikation und im Code, Fälle, die das Format nicht ausdrücken kann. |
| PyPI: so4ag | Das Python-Paket: pip install so4ag |
| Releases | Das 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 Registry | Der Eintrag unseres MCP-Servers: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Kurze Fragen und ein Gespräch mit anderen, die das Format ausprobieren. |
| DEV: @soqvercom | Technische Artikel und Anleitungen zum Format. |
| daily.dev: @soqver | Links zu neuen Artikeln für Entwickler. |
| X · YouTube | Neuigkeiten zum Format und kurze Demos. |
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].