SOQVER Klargjør en kilde
Norsk

Veiledning for utviklere

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.

Alt på ett sted

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

1. Hent koden

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

2. Valider en kilde

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.

3. Spør om et faktum kan brukes

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.

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

GrunnHva det betyr
expired, not_yet_validPå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_applicableUtgiveren oppgir uttrykkelig at verdien ikke er kjent eller ikke gjelder. Ukjent er ikke null.
disputedPåstanden er omstridt.
no_trust_policyOppgaven 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_authenticatedKilden 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_claimsTo gjeldende påstander oppgir ulike verdier for det samme. Leseren bruker ingen av dem og velger aldri en vinner i det stille.
invalid_sourceKilden bryter formatets struktur (for eksempel en påstand uten belegg eller en uleselig dato). Ingenting av den brukes.
unsupported_versionKilden 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.

4. Publiser egen kilde

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"
    }
  ]
}
  1. Lagre filen som so4ag.json og kontroller den med validatoren (trinn 2).
  2. Tilby den over HTTPS på domenet ditt på /so4ag.json med typen application/json.
  3. Legg til en lenke til kilden på sidene for mennesker:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. For å ha de samme faktaene inne i siden konverterer du kilden til JSON-LD og legger resultatet i en <script type="application/ld+json">-tagg. Konverteringen er tapsfri.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Gi hver påstand en gyldighetsslutt (valid_until), og bekreft eller endre påstanden før den passeres. Etter det tidspunktet slutter lesere å bruke den.

Enhver bransje: den generelle profilen og Deres egen profil

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.

ProfilFor hvem
GenerellEnhver 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, DetaljhandelDet som er særskilt for bransjen: depositum, kilometergrense, frakt, returer.
Deres egenAlt 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."
    }
  }
}
  1. Server filen over HTTPS på adressen som er oppgitt i id, og legg den adressen til i profiles i Deres kilde.
  2. Skriv egenskapen til en påstand som namespace + navn, det vil si https://dental.example/so4ag-profile#emergencySlot.
  3. Kontroller 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 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.

5. Les publiserte kilder gjennom API-et

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.

6. Koble til en agent gjennom MCP

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øyHva det gjør
list_sourcesLister de publiserte kildene.
get_sourceReturnerer hele kilden til én virksomhet.
get_claimsVurderer påstandene i en kilde for en gitt egenskap og gitte betingelser.
check_claimSier 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"}'

7. Skriv en egen leser

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.

Hvor De finner prosjektet

StedHva det er til
GitHub: soqvercom/so4agKode, spesifikasjon, samsvarssuite og utgivelser. Det er her formatet utvikles.
GitHub DiscussionsStedet for fellesskapet: spørsmål, forslag og erfaring med formatet. Vi svarer her.
GitHub IssuesFeil i spesifikasjonen og koden, tilfeller formatet ikke kan uttrykke.
PyPI: so4agPython-pakken: pip install so4ag
UtgivelserJavaScript-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 RegistryOppføringen for MCP-serveren vår: com.soqver/so4ag
Discord: SOQVER · SO4AGKorte spørsmål og en samtale med andre som prøver formatet.
DEV: @soqvercomTekniske artikler og veiledninger om formatet.
daily.dev: @soqverLenker til nye artikler for utviklere.
X · YouTubeNyheter om formatet og korte demoer.

Tilbakemeldinger og feil

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