SOQVER Bron voorbereiden
Nederlands

Gids voor ontwikkelaars

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.

Alles op één plek

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

1. De code ophalen

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

2. Een bron valideren

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.

3. Vragen of een feit gebruikt mag worden

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.

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

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.

RedenWat het betekent
expired, not_yet_validDe 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_applicableDe uitgever stelt uitdrukkelijk dat de waarde niet bekend is of niet van toepassing is. Onbekend is niet nul.
disputedDe bewering wordt betwist.
no_trust_policyDe 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_authenticatedDe 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_claimsTwee actuele beweringen vermelden verschillende waarden voor hetzelfde. De lezer gebruikt geen van beide en kiest nooit stilzwijgend een winnaar.
invalid_sourceDe bron breekt de structuur van het formaat (bijvoorbeeld een bewering zonder bewijs of een onleesbare datum). Niets ervan wordt gebruikt.
unsupported_versionDe 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.

4. Uw eigen bron publiceren

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"
    }
  ]
}
  1. Sla het bestand op als so4ag.json en controleer het met de validator (stap 2).
  2. Bied het via HTTPS aan op uw domein op /so4ag.json met het type application/json.
  3. Voeg een koppeling naar de bron toe aan de pagina's voor mensen:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Om dezelfde feiten in de pagina te hebben, zet u de bron om naar JSON-LD en plaatst u het resultaat in een <script type="application/ld+json">-tag. De omzetting is verliesvrij.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Geef elke bewering een einde van de geldigheid (valid_until) en bevestig of wijzig de bewering voordat dat verstrijkt. Na dat tijdstip gebruiken lezers haar niet meer.

Elke branche: het profiel Algemeen en uw eigen profiel

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.

ProfielVoor wie
AlgemeenElk 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, DetailhandelWat specifiek is voor de branche: borg, kilometerlimiet, verzending, retouren.
Uw eigenAl 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."
    }
  }
}
  1. Bied het bestand aan via HTTPS op het adres in id en voeg dat adres toe aan profiles in uw bron.
  2. Schrijf de eigenschap van een claim als namespace + naam, dat is https://dental.example/so4ag-profile#emergencySlot.
  3. Controleer het profiel en de bron:
    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

Een 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.

5. Gepubliceerde bronnen lezen via de API

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.

6. Een agent verbinden via MCP

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
ToolWat het doet
list_sourcesSomt de gepubliceerde bronnen op.
get_sourceGeeft de volledige bron van één bedrijf terug.
get_claimsBeoordeelt de beweringen van een bron voor een gegeven eigenschap en voorwaarden.
check_claimGeeft 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"}'

7. Uw eigen lezer schrijven

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.

Waar u het project vindt

PlaatsWaar het voor dient
GitHub: soqvercom/so4agCode, specificatie, conformiteitssuite en releases. Hier wordt het formaat ontwikkeld.
GitHub DiscussionsDe plek voor de gemeenschap: vragen, voorstellen en ervaring met het formaat. Wij antwoorden hier.
GitHub IssuesFouten in de specificatie en de code, gevallen die het formaat niet kan uitdrukken.
PyPI: so4agHet Python-pakket: pip install so4ag
ReleasesHet 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 RegistryDe vermelding van onze MCP-server: com.soqver/so4ag
Discord: SOQVER · SO4AGKorte vragen en een gesprek met anderen die het formaat uitproberen.
DEV: @soqvercomTechnische artikelen en praktische handleidingen over het formaat.
daily.dev: @soqverLinks naar nieuwe artikelen voor ontwikkelaars.
X · YouTubeNieuws over het formaat en korte demo's.

Feedback en fouten

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].