SO4AG is een open formaat voor bedrijfsfeiten: elk feit draagt zijn betekenis, reikwijdte, herkomst en geldigheid. Een lezer beantwoordt één vraag: mag dit feit voor deze taak op dit moment worden gebruikt, en zo niet, waarom niet.
Het formaat is gratis en heeft geen account nodig. De code is gelicentieerd onder Apache-2.0, de tekst van de specificatie onder CC BY 4.0.
Repository op GitHub · specificatie · JSON Schema · conformiteitssuite · JSON-LD · validator in de browser · wat werkt
Inhoud: 1. De code ophalen · 2. Een bron valideren · 3. Naar een feit vragen · 4. Uw eigen bron publiceren · 5. API · 6. MCP · 7. Uw eigen lezer · Elke branche · Waar u het project vindt
U hebt Git en Node.js 20 of nieuwer nodig. De Python-lezer heeft alleen de standaardbibliotheek nodig (Python 3.10 of nieuwer).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
De laatste opdracht voert de tests van de referentiecode uit tegen de conformiteitssuite. Ze moeten allemaal slagen.
In uw eigen project installeert u de pakketten elk met één commando:
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
De validator leest een bestand of een adres. Hij begrijpt SO4AG JSON, de JSON-LD-vorm en een HTML-pagina met de JSON-LD erin.
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
Het antwoord begint met VALID of INVALID. Bij een ongeldige bron volgt een lijst met fouten en hun plaats in het bestand. Zonder iets te installeren werkt hetzelfde in de validator in de browser.
Een geldige bron bewijst alleen een correcte structuur. Zij zegt niet dat het feit waar is.
Een taak geeft aan welke eigenschap u opvraagt en onder welke voorwaarden (reikwijdte). De lezer geeft elke overeenkomende bewering terug, met het antwoord of zij bruikbaar is en de redenen wanneer zij dat niet is.
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
Probeer hetzelfde zonder de vestigingsvoorwaarde of op een ander tijdstip (--now 2027-06-01T12:00:00Z, in JavaScript het derde argument { now: new Date(…) }). De bewering is dan niet meer bruikbaar en de lezer zegt waarom.
| Reden | Wat het betekent |
|---|---|
expired, not_yet_valid | De bewering geldt niet op het tijdstip van de vraag. |
scope_mismatch:<key> | De bewering geldt voor een andere waarde van de voorwaarde, bijvoorbeeld een andere vestiging. |
scope_not_in_task:<key> | De bewering wordt beperkt door een voorwaarde die de taak niet vermeldt. Zonder die voorwaarde kan niemand zeggen of de bewering van toepassing is. |
unknown, not_applicable | De uitgever stelt uitdrukkelijk dat de waarde niet bekend is of niet van toepassing is. Onbekend is niet nul. |
disputed | De bewering wordt betwist. |
no_trust_policy | De taak vraagt om een beoordeelde bewering, maar zegt niet wie zij vertrouwt. Wie te vertrouwen is de beslissing van degene die de bewering leest. |
attestation_not_authenticated | De bron bevat een attestatie met de naam van een uitgever die u vertrouwt, maar u hebt die niet bij de uitgever geauthenticeerd. Een naam die in de bron staat, is geen bewijs. |
conflicting_claims | Twee actuele beweringen vermelden verschillende waarden voor hetzelfde. De lezer gebruikt geen van beide en kiest nooit stilzwijgend een winnaar. |
invalid_source | De bron breekt de structuur van het formaat (bijvoorbeeld een bewering zonder bewijs of een onleesbare datum). Niets ervan wordt gebruikt. |
unsupported_version | De bron is van een versie van het formaat die de lezer niet kent. Zij wordt niet gelezen volgens de regels van een andere versie. |
De volledige lijst met redenen en regels staat in de specificatie.
Een bron is één JSON-bestand. De kleinste bruikbare vorm heeft een uitgever en één bewering:
{
"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 en controleer het met de validator (stap 2)./so4ag.json met het type application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">-tag. De omzetting is verliesvrij. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) en bevestig of wijzig de bewering voordat dat verstrijkt. Na dat tijdstip gebruiken lezers haar niet meer.Het formaat is niet aan een branche gebonden. Eigenschappen (wat een feit betekent, het type en de eenheid, en welke voorwaarden het beperken) worden door een profiel bepaald, en één bron kan meerdere profielen samen gebruiken.
| Profiel | Voor wie |
|---|---|
| Algemeen | Elk bedrijf of elke organisatie: exploitant, locaties en openingstijden, contacten, talen, wat het aanbiedt en voor hoeveel, betaling, reservering, reactie- en levertijden, annulering, garantie, toegankelijkheid, licenties, beschikbaarheid. 26 eigenschappen. |
| Voertuigverhuur, Detailhandel | Wat specifiek is voor de branche: borg, kilometerlimiet, verzending, retouren. |
| Uw eigen | Al het overige. Een profiel is een JSON-bestand op uw domein; u vraagt niemand en registreert niets. |
Uw eigen profiel beschrijft uw eigenschappen op dezelfde wijze als de onze: label, beschrijving, waardetype, eenheden, toegestane codes en voorwaarden. De kleinste vorm:
{
"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 en voeg dat adres toe aan profiles in uw bron.namespace + naam, dat is 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.jsonEen lezer die uw profiel niet kent, gebruikt de claim toch wanneer de taak de voorwaarden ervan vermeldt; doet de taak dat niet, dan wordt de claim niet gebruikt. De veiligheidsregels van het formaat gelden daarom voor elk profiel op dezelfde wijze. Een volledig voorbeeld van een tandartspraktijk met het profiel Algemeen en een eigen profiel staat in de repository: general-dental.json. Schema van een profiel: profile.schema.json.
Liever het bestand niet met de hand schrijven? De SOQVER-dienst stelt een voorstel op op basis van uw website. U bevestigt de feiten en publiceert de bron bij ons of downloadt deze voor uw eigen domein: een bron voorbereiden.
De interface is alleen-lezen en heeft geen account en geen sleutel nodig.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
Het eerste adres geeft de lijst van bronnen die een bedrijf heeft gepubliceerd of bevestigd. Het tweede beoordeelt de beweringen van één bron voor uw taak en geeft voor elk usable en reasons terug. Elke bron is ook een pagina voor mensen (/s/<slug>/), een bestand /s/<slug>/so4ag.json en een JSON-LD-vorm /s/<slug>/facts.jsonld.
De MCP-server is alleen-lezen, heeft geen account nodig en gebruikt het Streamable HTTP-transport. In het officiële MCP Registry staat hij vermeld als com.soqver/so4ag.
https://soqver.com/mcp
| Tool | Wat het doet |
|---|---|
list_sources | Somt de gepubliceerde bronnen op. |
get_source | Geeft de volledige bron van één bedrijf terug. |
get_claims | Beoordeelt de beweringen van een bron voor een gegeven eigenschap en voorwaarden. |
check_claim | Geeft aan of één bewering nu gebruikt mag worden, en waarom niet. |
Voer in een client die externe MCP-servers ondersteunt het bovenstaande adres in. U kunt het antwoord van de server ook vanaf de opdrachtregel controleren:
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"}'
De conformiteitssuite is gewone JSON en heeft niets van onze code nodig. Deze bevat twee geldige bronnen in drie vormen, de verwachte digests van de beweringen, 45 evaluatiegevallen, 31 validatiegevallen, 10 gevallen voor de volledige bron en 25 vectoren van de canonieke vorm (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Wanneer een lezer of een validator de suite doorstaat, staat beschreven in de beschrijving van de conformiteitssuite. De Python-lezer is onafhankelijk van de referentiecode geschreven en doorstaat dezelfde suite; u kunt hem als model gebruiken.
| Plaats | Waar het voor dient |
|---|---|
| GitHub: soqvercom/so4ag | Code, specificatie, conformiteitssuite en releases. Hier wordt het formaat ontwikkeld. |
| GitHub Discussions | De plek voor de gemeenschap: vragen, voorstellen en ervaring met het formaat. Wij antwoorden hier. |
| GitHub Issues | Fouten in de specificatie en de code, gevallen die het formaat niet kan uitdrukken. |
| PyPI: so4ag | Het Python-pakket: pip install so4ag |
| Releases | Het JavaScript-pakket en de bestanden van elke versie: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Een permanente link naar de releases om te citeren in artikelen en documentatie. |
| MCP Registry | De vermelding van onze MCP-server: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Korte vragen en een gesprek met anderen die het formaat uitproberen. |
| DEV: @soqvercom | Technische artikelen en praktische handleidingen over het formaat. |
| daily.dev: @soqver | Links naar nieuwe artikelen voor ontwikkelaars. |
| X · YouTube | Nieuws over het formaat en korte demo's. |
Een feit gevonden dat het formaat niet kan uitdrukken, of twee lezers die verschillend antwoorden? Leg het vast als een issue op GitHub. Meld een kwetsbaarheid per e-mail aan [email protected].