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.
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
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
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.
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.
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
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.
| Begrundelse | Hvad det betyder |
|---|---|
expired, not_yet_valid | Udsagnet 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_applicable | Udgiveren angiver udtrykkeligt, at værdien ikke er kendt eller ikke gælder. Ukendt er ikke nul. |
disputed | Udsagnet er bestridt. |
no_trust_policy | Opgaven 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_authenticated | Kilden 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_claims | To gældende påstande angiver forskellige værdier for det samme. Læseren bruger ingen af dem og udpeger aldrig tavst en vinder. |
invalid_source | Kilden bryder formatets struktur (for eksempel en påstand uden evidens eller en ulæselig dato). Intet af den bruges. |
unsupported_version | Kilden 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.
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"
}
]
}
so4ag.json, og kontrollér den med validatoren (trin 2)./so4ag.json med typen application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">-tag. Konverteringen er tabsfri. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until), og bekræft eller ændr udsagnet, før den passerer. Efter det tidspunkt holder læserne op med at anvende det.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.
| Profil | Til hvem |
|---|---|
| Generel | Enhver 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, Detailhandel | Det, der er specifikt for branchen: depositum, kilometergrænse, forsendelse, returnering. |
| Deres egen | Alt 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."
}
}
}
id, og tilføj den adresse til profiles i Deres kilde.namespace + navn, det vil sige 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.jsonEn 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.
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.
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øj | Hvad det gør |
|---|---|
list_sources | Viser de offentliggjorte kilder. |
get_source | Returnerer hele kilden for én virksomhed. |
get_claims | Vurderer en kildes påstande for en given egenskab og givne betingelser. |
check_claim | Angiver, 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"}'
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.
| Sted | Hvad det er til |
|---|---|
| GitHub: soqvercom/so4ag | Kode, specifikation, overensstemmelsessuite og udgivelser. Det er her, formatet udvikles. |
| GitHub Discussions | Stedet for fællesskabet: spørgsmål, forslag og erfaringer med formatet. Vi svarer her. |
| GitHub Issues | Fejl i specifikationen og koden samt tilfælde, som formatet ikke kan udtrykke. |
| PyPI: so4ag | Python-pakken: pip install so4ag |
| Udgivelser | JavaScript-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 Registry | Posten for vores MCP-server: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Korte spørgsmål og en samtale med andre, der afprøver formatet. |
| DEV: @soqvercom | Tekniske artikler og vejledninger om formatet. |
| daily.dev: @soqver | Links til nye artikler for udviklere. |
| X · YouTube | Nyheder om formatet og korte demoer. |
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].