SOQVER Forbered en kilde
Dansk

Vejledning til udviklere

SO4AG er et åbent format til forretningsfakta: hvert faktum bærer sin betydning, sit omfang, sin oprindelse og sin gyldighed. En læser besvarer ét spørgsmål: må dette faktum anvendes til denne opgave på dette tidspunkt, og hvis ikke, hvorfor ikke.

Formatet er gratis og kræver ingen konto. Koden er licenseret under Apache-2.0, specifikationens tekst under CC BY 4.0.

Alt samlet ét sted

Arkiv på GitHub · specifikation · JSON Schema · overensstemmelsessuite · JSON-LD · validator i browseren · hvad der virker

Indhold: 1. Hent koden · 2. Validér en kilde · 3. Spørg om et faktum · 4. Udgiv Deres egen kilde · 5. API · 6. MCP · 7. Deres egen læser · Enhver branche · Hvor De finder projektet

1. Hent koden

De skal bruge Git og Node.js 20 eller nyere. Python-læseren kræver kun standardbiblioteket (Python 3.10 eller nyere).

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

Den sidste kommando kører testene af referencekoden mod overensstemmelsessuiten. Alle bør bestå.

I Deres eget projekt installeres pakkerne med én kommando hver:

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. Validér en kilde

Validatoren læser en fil eller en adresse. Den forstår SO4AG JSON, JSON-LD-formen og en HTML-side med JSON-LD indeni.

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

Svaret begynder med VALID eller INVALID. For en ugyldig kilde følger en liste over fejl med deres placering i filen. Uden at installere noget fungerer det samme i validatoren i browseren.

En gyldig kilde beviser kun, at strukturen er korrekt. Den siger ikke, at faktummet er sandt.

3. Spørg, om en oplysning må bruges

En opgave angiver, hvilken egenskab De spørger om, og for hvilke betingelser (omfang). Læseren returnerer hvert matchende udsagn med svaret på, om det er anvendeligt, og begrundelserne, når det ikke er det.

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

Prøv det samme uden filialbetingelsen eller på et andet tidspunkt (--now 2027-06-01T12:00:00Z, i JavaScript det tredje argument { now: new Date(…) }). Udsagnet ophører med at være anvendeligt, og læseren siger hvorfor.

BegrundelseHvad det betyder
expired, not_yet_validUdsagnet gælder ikke på spørgsmålets tidspunkt.
scope_mismatch:<key>Udsagnet gælder for en anden værdi af betingelsen, for eksempel en anden filial.
scope_not_in_task:<key>Udsagnet er begrænset af en betingelse, som opgaven ikke angiver. Uden den kan ingen sige, om udsagnet gælder.
unknown, not_applicableUdgiveren angiver udtrykkeligt, at værdien ikke er kendt eller ikke gælder. Ukendt er ikke nul.
disputedUdsagnet er bestridt.
no_trust_policyOpgaven beder om et gennemgået udsagn, men angiver ikke, hvem den stoler på. Hvem man stoler på, afgøres af den, der læser udsagnet.
attestation_not_authenticatedKilden bærer en attestation med navnet på en udsteder, som De har tillid til, men De har ikke autentificeret den hos udstederen. Et navn, der står skrevet i kilden, er ikke et bevis.
conflicting_claimsTo gældende påstande angiver forskellige værdier for det samme. Læseren bruger ingen af dem og udpeger aldrig tavst en vinder.
invalid_sourceKilden bryder formatets struktur (for eksempel en påstand uden evidens eller en ulæselig dato). Intet af den bruges.
unsupported_versionKilden er i en version af formatet, som læseren ikke kender. Den læses ikke efter reglerne for en anden version.

Den fulde liste over begrundelser og regler står i specifikationen.

4. Offentliggør Deres egen kilde

En kilde er én JSON-fil. Den mindste brugbare form har en udgiver og ét udsagn:

{
  "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. Gem filen som so4ag.json, og kontrollér den med validatoren (trin 2).
  2. Udbyd den via HTTPS på Deres domæne på /so4ag.json med typen application/json.
  3. Tilføj et link til kilden på siderne for mennesker:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. For at have de samme fakta inde i siden skal De konvertere kilden til JSON-LD og lægge resultatet i et <script type="application/ld+json">-tag. Konverteringen er tabsfri.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Giv hvert udsagn en afslutning på gyldigheden (valid_until), og bekræft eller ændr udsagnet, før den passerer. Efter det tidspunkt holder læserne op med at anvende det.

Enhver branche: den generelle profil og Deres egen profil

Formatet er ikke bundet til en branche. Egenskaber (hvad et faktum betyder, dets type og enhed, og hvilke betingelser der begrænser det) fastsættes af en profil, og én kilde kan bruge flere profiler sammen.

ProfilTil hvem
GenerelEnhver virksomhed eller organisation: operatør, steder og åbningstider, kontakter, sprog, hvad den tilbyder og til hvilken pris, betaling, booking, svartider og leveringstider, annullering, garanti, tilgængelighed, licenser, rådighed. 26 egenskaber.
Biludlejning, DetailhandelDet, der er specifikt for branchen: depositum, kilometergrænse, forsendelse, returnering.
Deres egenAlt andet. En profil er en JSON-fil på Deres domæne; De spørger ingen og registrerer intet.

Deres egen profil beskriver Deres egenskaber på samme måde som vores: etiket, beskrivelse, værditype, enheder, tilladte koder og betingelser. Den mindste 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. Server filen via HTTPS på den adresse, der er angivet i id, og tilføj den adresse til profiles i Deres kilde.
  2. Skriv egenskaben for en påstand som namespace + navn, det vil sige https://dental.example/so4ag-profile#emergencySlot.
  3. Kontrollér profilen og kilden:
    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

En læser, der ikke kender Deres profil, bruger stadig påstanden, når opgaven angiver dens betingelser; når opgaven ikke gør det, bruges påstanden ikke. Formatets sikkerhedsregler gælder derfor ens for alle profiler. Et fuldstændigt eksempel på en tandlægepraksis med den generelle profil og dens egen profil findes i repositoriet: general-dental.json. Skema for en profil: profile.schema.json.

Vil De hellere ikke skrive filen i hånden? SOQVER-tjenesten udarbejder et forslag ud fra Deres websted, De bekræfter fakta og udgiver kilden hos os eller henter den til Deres eget domæne: forbered en kilde.

5. Læs offentliggjorte kilder via API'et

Grænsefladen er skrivebeskyttet og kræver hverken konto eller nøgle.

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

Den første adresse returnerer listen over kilder, som en virksomhed har offentliggjort eller bekræftet. Den anden vurderer påstandene i én kilde i forhold til Deres opgave og returnerer usable og reasons for hver. Hver kilde er også en side for mennesker (/s/<slug>/), en fil /s/<slug>/so4ag.json og en JSON-LD-form /s/<slug>/facts.jsonld.

6. Tilslut en agent via MCP

MCP-serveren er skrivebeskyttet, kræver ingen konto og bruger transporten Streamable HTTP. I det officielle MCP Registry er den opført som com.soqver/so4ag.

https://soqver.com/mcp
VærktøjHvad det gør
list_sourcesViser de offentliggjorte kilder.
get_sourceReturnerer hele kilden for én virksomhed.
get_claimsVurderer en kildes påstande for en given egenskab og givne betingelser.
check_claimAngiver, om én påstand må bruges nu, og hvorfor ikke.

I en klient, der understøtter fjern-MCP-servere, indtaster De adressen ovenfor. De kan også kontrollere serverens svar fra kommandolinjen:

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. Skriv Deres egen læser

Overensstemmelsessuiten er ren JSON og kræver ingen af vores kode. Den indeholder to gyldige kilder i tre former, de forventede digests af påstandene, 45 evalueringstilfælde, 31 valideringstilfælde, 10 tilfælde for hele kilden og 25 vektorer af den kanoniske form (RFC 8785).

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

Hvornår en læser eller en validator består suiten, er beskrevet i beskrivelsen af overensstemmelsessuiten. Python-læseren er skrevet uafhængigt af referencekoden og består den samme suite; De kan bruge den som model.

Hvor De finder projektet

StedHvad det er til
GitHub: soqvercom/so4agKode, specifikation, overensstemmelsessuite og udgivelser. Det er her, formatet udvikles.
GitHub DiscussionsStedet for fællesskabet: spørgsmål, forslag og erfaringer med formatet. Vi svarer her.
GitHub IssuesFejl i specifikationen og koden samt tilfælde, som formatet ikke kan udtrykke.
PyPI: so4agPython-pakken: pip install so4ag
UdgivelserJavaScript-pakken og filerne til hver version: npm install github:soqvercom/so4ag
Zenodo (DOI)Et permanent link til udgivelserne til citering i artikler og dokumentation.
MCP RegistryPosten for vores MCP-server: com.soqver/so4ag
Discord: SOQVER · SO4AGKorte spørgsmål og en samtale med andre, der afprøver formatet.
DEV: @soqvercomTekniske artikler og vejledninger om formatet.
daily.dev: @soqverLinks til nye artikler for udviklere.
X · YouTubeNyheder om formatet og korte demoer.

Tilbagemelding og fejl

Har De fundet en oplysning, som formatet ikke kan udtrykke, eller to læsere, der svarer forskelligt? Skriv det som et issue på GitHub. Rapportér venligst en sårbarhed pr. e-mail til [email protected].