SO4AG er et åpent format for forretningsfakta: hvert faktum bærer sin betydning, sitt omfang, sin opprinnelse og sin gyldighet. En leser svarer på ett spørsmål: kan dette faktumet brukes til denne oppgaven på dette tidspunktet, og hvis ikke, hvorfor ikke.
Formatet er gratis og krever ingen konto. Koden er lisensiert under Apache-2.0 og teksten i spesifikasjonen under CC BY 4.0.
Repositorium på GitHub · spesifikasjon · JSON Schema · samsvarssuite · JSON-LD · validator i nettleseren · hva som virker
Innhold: 1. Hent koden · 2. Valider en kilde · 3. Spør om et faktum · 4. Publiser Deres egen kilde · 5. API · 6. MCP · 7. Deres egen leser · Enhver bransje · Hvor prosjektet finnes
De trenger Git og Node.js 20 eller nyere. Python-leseren trenger bare standardbiblioteket (Python 3.10 eller nyere).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
Den siste kommandoen kjører testene av referansekoden mot samsvarssuiten. Alle skal bestå.
Pakkene installeres i ditt eget prosjekt 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 leser en fil eller en adresse. Den forstår SO4AG JSON, JSON-LD-formen og en HTML-side med JSON-LD inni.
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 starter med VALID eller INVALID. For en ugyldig kilde følger en liste over feil med deres plass i filen. Uten å installere noe fungerer det samme i validatoren i nettleseren.
En gyldig kilde beviser bare korrekt struktur. Den sier ikke at faktumet er sant.
En oppgave sier hvilken egenskap du spør om, og for hvilke betingelser (omfang). Leseren returnerer hver samsvarende påstand med svaret på om den kan brukes, og grunnene når den ikke kan 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 uten filialbetingelsen eller på et annet tidspunkt (--now 2027-06-01T12:00:00Z, i JavaScript det tredje argumentet { now: new Date(…) }). Påstanden slutter å være brukbar, og leseren sier hvorfor.
| Grunn | Hva det betyr |
|---|---|
expired, not_yet_valid | Påstanden gjelder ikke på tidspunktet for spørsmålet. |
scope_mismatch:<key> | Påstanden gjelder for en annen verdi av betingelsen, for eksempel en annen filial. |
scope_not_in_task:<key> | Påstanden er begrenset av en betingelse oppgaven ikke oppgir. Uten den kan ingen si om påstanden gjelder. |
unknown, not_applicable | Utgiveren oppgir uttrykkelig at verdien ikke er kjent eller ikke gjelder. Ukjent er ikke null. |
disputed | Påstanden er omstridt. |
no_trust_policy | Oppgaven ber om en gjennomgått påstand, men sier ikke hvem den stoler på. Hvem man skal stole på, er beslutningen til den som leser påstanden. |
attestation_not_authenticated | Kilden har en attestasjon med navnet på en utsteder De stoler på, men De har ikke autentisert den hos utstederen. Et navn som står i kilden, er ikke et bevis. |
conflicting_claims | To gjeldende påstander oppgir ulike verdier for det samme. Leseren bruker ingen av dem og velger aldri en vinner i det stille. |
invalid_source | Kilden bryter formatets struktur (for eksempel en påstand uten belegg eller en uleselig dato). Ingenting av den brukes. |
unsupported_version | Kilden er av en versjon av formatet som leseren ikke kjenner. Den leses ikke etter reglene for en annen versjon. |
Den fullstendige listen over grunner og regler finnes i spesifikasjonen.
En kilde er én JSON-fil. Den minste nyttige formen har en utgiver og én påstand:
{
"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 kontroller den med validatoren (trinn 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">-tagg. Konverteringen er tapsfri. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until), og bekreft eller endre påstanden før den passeres. Etter det tidspunktet slutter lesere å bruke den.Formatet er ikke knyttet til en bransje. Egenskaper (hva et faktum betyr, typen og enheten, og hvilke vilkår som begrenser det) fastsettes av en profil, og én kilde kan bruke flere profiler sammen.
| Profil | For hvem |
|---|---|
| Generell | Enhver virksomhet eller organisasjon: operatør, steder og åpningstider, kontakter, språk, hva den tilbyr og til hvilken pris, betaling, bestilling, svartider og leveringstider, avbestilling, garanti, universell utforming, lisenser, tilgjengelighet. 26 egenskaper. |
| Kjøretøyutleie, Detaljhandel | Det som er særskilt for bransjen: depositum, kilometergrense, frakt, returer. |
| Deres egen | Alt annet. En profil er en JSON-fil på Deres domene; De spør ingen og registrerer ingenting. |
Deres egen profil beskriver Deres egenskaper på samme måte som våre: etikett, beskrivelse, verditype, enheter, tillatte koder og vilkår. Den minste formen:
{
"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 legg den adressen til i profiles i Deres kilde.namespace + navn, det vil si 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 leser som ikke kjenner Deres profil, bruker likevel påstanden når oppgaven angir vilkårene; når oppgaven ikke gjør det, brukes ikke påstanden. Sikkerhetsreglene i formatet gjelder derfor likt for alle profiler. Et fullstendig eksempel på en tannlegepraksis med General-profilen og egen profil ligger i repositoriet: general-dental.json. Skjema for en profil: profile.schema.json.
Vil du helst ikke skrive filen for hånd? SOQVER-tjenesten lager et forslag ut fra nettstedet ditt. Du bekrefter faktaene og publiserer kilden hos oss eller laster den ned til ditt eget domene: forbered en kilde.
Grensesnittet er skrivebeskyttet og krever verken konto eller nøkkel.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
Den første adressen returnerer listen over kilder et selskap har publisert eller bekreftet. Den andre vurderer påstandene i én kilde for Deres oppgave 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, krever ingen konto og bruker transporten Streamable HTTP. I det offisielle MCP Registry står den oppført som com.soqver/so4ag.
https://soqver.com/mcp
| Verktøy | Hva det gjør |
|---|---|
list_sources | Lister de publiserte kildene. |
get_source | Returnerer hele kilden til én virksomhet. |
get_claims | Vurderer påstandene i en kilde for en gitt egenskap og gitte betingelser. |
check_claim | Sier om én påstand kan brukes nå, og hvorfor ikke. |
I en klient som støtter eksterne MCP-servere, skriver De inn 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"}'
Samsvarssuiten er ren JSON og trenger ingen av koden vår. Den inneholder to gyldige kilder i tre former, de forventede digestene for påstandene, 45 evalueringstilfeller, 31 valideringstilfeller, 10 tilfeller for hele kilden og 25 vektorer for den kanoniske formen (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Når en leser eller en validator består suiten, er det beskrevet i beskrivelsen av samsvarssuiten. Python-leseren ble skrevet uavhengig av referansekoden og består samme suite. De kan bruke den som modell.
| Sted | Hva det er til |
|---|---|
| GitHub: soqvercom/so4ag | Kode, spesifikasjon, samsvarssuite og utgivelser. Det er her formatet utvikles. |
| GitHub Discussions | Stedet for fellesskapet: spørsmål, forslag og erfaring med formatet. Vi svarer her. |
| GitHub Issues | Feil i spesifikasjonen og koden, tilfeller formatet ikke kan uttrykke. |
| PyPI: so4ag | Python-pakken: pip install so4ag |
| Utgivelser | JavaScript-pakken og filene for hver versjon: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | En permanent lenke til utgivelsene for sitering i artikler og dokumentasjon. |
| MCP Registry | Oppføringen for MCP-serveren vår: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Korte spørsmål og en samtale med andre som prøver formatet. |
| DEV: @soqvercom | Tekniske artikler og veiledninger om formatet. |
| daily.dev: @soqver | Lenker til nye artikler for utviklere. |
| X · YouTube | Nyheter om formatet og korte demoer. |
Har De funnet et faktum som formatet ikke kan uttrykke, eller to lesere som svarer ulikt? Skriv det som en sak på GitHub. Meld en sårbarhet per e-post til [email protected].