SOQVER Förbered en källa
Svenska

Guide för utvecklare

SO4AG är ett öppet format för affärsfakta: varje faktum bär sin betydelse, sin omfattning, sitt ursprung och sin giltighet. En läsare besvarar en fråga: får detta faktum användas för den här uppgiften vid den här tidpunkten, och om inte, varför inte.

Formatet är kostnadsfritt och kräver inget konto. Koden licensieras under Apache-2.0, specifikationens text under CC BY 4.0.

Allt på ett ställe

Arkiv på GitHub · specifikation · JSON Schema · överensstämmelsesvit · JSON-LD · validator i webbläsaren · vad som fungerar

Innehåll: 1. Hämta koden · 2. Validera en källa · 3. Fråga om ett faktum · 4. Publicera er egen källa · 5. API · 6. MCP · 7. Er egen läsare · Alla branscher · Var projektet finns

1. Hämta koden

Ni behöver Git och Node.js 20 eller nyare. Python-läsaren behöver bara standardbiblioteket (Python 3.10 eller nyare).

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

Det sista kommandot kör referenskodens tester mot överensstämmelsessviten. Alla bör passera.

I ert eget projekt installeras paketen med ett kommando vardera:

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. Validera en källa

Validatorn läser en fil eller en adress. Den förstår SO4AG JSON, JSON-LD-formen och en HTML-sida med JSON-LD inuti.

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 börjar med VALID eller INVALID. För en ogiltig källa följer en lista över fel med deras plats i filen. Utan att installera något fungerar detsamma i validatorn i webbläsaren.

En giltig källa bevisar endast korrekt struktur. Den säger inte att faktumet är sant.

3. Fråga om ett faktum får användas

En uppgift anger vilken egenskap ni frågar om och för vilka villkor (omfattning). Läsaren returnerar varje matchande påstående med svaret på om det är användbart, och skälen när det inte är 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

Prova samma sak utan filialvillkoret eller vid en annan tidpunkt (--now 2027-06-01T12:00:00Z, i JavaScript det tredje argumentet { now: new Date(…) }). Påståendet slutar vara användbart och läsaren säger varför.

SkälVad det betyder
expired, not_yet_validPåståendet gäller inte vid tidpunkten för frågan.
scope_mismatch:<key>Påståendet gäller för ett annat värde av villkoret, till exempel en annan filial.
scope_not_in_task:<key>Påståendet begränsas av ett villkor som uppgiften inte anger. Utan det kan ingen säga om påståendet gäller.
unknown, not_applicableUtgivaren anger uttryckligen att värdet inte är känt eller inte gäller. Okänt är inte noll.
disputedPåståendet är omtvistat.
no_trust_policyUppgiften begär ett granskat påstående men anger inte vem den litar på. Vem man ska lita på är ett beslut för den som läser påståendet.
attestation_not_authenticatedKällan bär en attestering med namnet på en utfärdare som ni litar på, men ni har inte autentiserat den hos utfärdaren. Ett namn som står i källan är inget bevis.
conflicting_claimsTvå gällande påståenden anger olika värden för samma sak. Läsaren använder inget av dem och utser aldrig en vinnare i det tysta.
invalid_sourceKällan bryter mot formatets struktur (till exempel ett påstående utan belägg eller ett oläsbart datum). Inget av den används.
unsupported_versionKällan är av en version av formatet som läsaren inte känner till. Den läses inte enligt reglerna för en annan version.

Den fullständiga listan över skäl och regler finns i specifikationen.

4. Publicera er egen källa

En källa är en JSON-fil. Den minsta användbara formen har en utgivare och ett påstående:

{
  "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. Spara filen som so4ag.json och kontrollera den med valideraren (steg 2).
  2. Tillhandahåll den via HTTPS på er domän på /so4ag.json med typen application/json.
  3. Lägg till en länk till källan på sidorna för människor:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. För att ha samma fakta inuti sidan konverterar ni källan till JSON-LD och lägger resultatet i en <script type="application/ld+json">-tagg. Konverteringen är förlustfri.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Ge varje påstående ett slut på giltigheten (valid_until) och bekräfta eller ändra påståendet innan det passerar. Efter den tidpunkten slutar läsarna att använda det.

Alla branscher: den allmänna profilen och er egen profil

Formatet är inte knutet till en bransch. Egenskaper (vad ett faktum betyder, dess typ och enhet samt vilka villkor som begränsar det) bestäms av en profil, och en källa kan använda flera profiler tillsammans.

ProfilFör vem
AllmänAlla företag och organisationer: operatör, platser och öppettider, kontakter, språk, vad den erbjuder och till vilket pris, betalning, bokning, svarstider och leveranstider, avbeställning, garanti, tillgänglighet, licenser, tillgång. 26 egenskaper.
Fordonsuthyrning, DetaljhandelDet som är specifikt för branschen: deposition, körsträckegräns, frakt, returer.
Er egenAllt annat. En profil är en JSON-fil på er domän; ni frågar ingen och registrerar ingenting.

Er egen profil beskriver era egenskaper på samma sätt som våra: etikett, beskrivning, värdetyp, enheter, tillåtna koder och villkor. Den minsta 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. Tillhandahåll filen via HTTPS på den adress som anges i id och lägg till den adressen i profiles i er källa.
  2. Skriv egenskapen för ett påstående som namespace + namn, det vill säga https://dental.example/so4ag-profile#emergencySlot.
  3. Kontrollera profilen och källan:
    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äsare som inte känner till er profil använder ändå påståendet när uppgiften anger dess villkor; när uppgiften inte gör det används påståendet inte. Formatets säkerhetsregler gäller därför för varje profil på samma sätt. Ett fullständigt exempel på en tandläkarpraktik med den allmänna profilen och en egen profil finns i repositoriet: general-dental.json. Schema för en profil: profile.schema.json.

Skriver ni hellre inte filen för hand? SOQVER-tjänsten tar fram ett förslag från er webbplats, ni bekräftar fakta och publicerar källan hos oss eller laddar ner den för er egen domän: förbered en källa.

5. Läs publicerade källor via API

Gränssnittet är skrivskyddat och kräver varken konto eller nyckel.

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

Den första adressen returnerar listan över källor som ett företag har publicerat eller bekräftat. Den andra utvärderar påståendena i en källa för er uppgift och returnerar usable och reasons för varje. Varje källa är också en sida för människor (/s/<slug>/), en fil /s/<slug>/so4ag.json och en JSON-LD-form /s/<slug>/facts.jsonld.

6. Anslut en agent via MCP

MCP-servern är skrivskyddad, kräver inget konto och använder transporten Streamable HTTP. I det officiella MCP Registry är den listad som com.soqver/so4ag.

https://soqver.com/mcp
VerktygVad det gör
list_sourcesListar de publicerade källorna.
get_sourceReturnerar hela källan för ett företag.
get_claimsUtvärderar en källas påståenden för en given egenskap och givna villkor.
check_claimAnger om ett påstående får användas nu, och varför inte.

I en klient som stöder fjärranslutna MCP-servrar anger ni adressen ovan. Ni kan också kontrollera serverns svar från kommandoraden:

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 er egen läsare

Konformitetssviten är ren JSON och behöver ingen av vår kod. Den innehåller två giltiga källor i tre former, de förväntade kondensaten av påståendena, 45 utvärderingsfall, 31 valideringsfall, 10 fall för hela källan och 25 vektorer av den kanoniska formen (RFC 8785).

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

När en läsare eller en validerare klarar sviten beskrivs i beskrivningen av överensstämmelsesviten. Python-läsaren skrevs oberoende av referenskoden och klarar samma svit. Ni kan använda den som modell.

Var ni hittar projektet

PlatsVad det är till för
GitHub: soqvercom/so4agKod, specifikation, testsvit för överensstämmelse och utgåvor. Här utvecklas formatet.
GitHub DiscussionsPlatsen för gemenskapen: frågor, förslag och erfarenheter av formatet. Vi svarar här.
GitHub IssuesFel i specifikationen och koden, fall som formatet inte kan uttrycka.
PyPI: so4agPython-paketet: pip install so4ag
UtgåvorJavaScript-paketet och filerna för varje version: npm install github:soqvercom/so4ag
Zenodo (DOI)En permanent länk till utgåvorna för citering i artiklar och dokumentation.
MCP RegistryPosten för vår MCP-server: com.soqver/so4ag
Discord: SOQVER · SO4AGSnabba frågor och en chatt med andra som prövar formatet.
DEV: @soqvercomTekniska artiklar och vägledningar om formatet.
daily.dev: @soqverLänkar till nya artiklar för utvecklare.
X · YouTubeNyheter om formatet och korta demonstrationer.

Synpunkter och fel

Har ni hittat ett faktum som formatet inte kan uttrycka, eller två läsare som svarar olika? Skriv det som ett ärende på GitHub. Rapportera en sårbarhet via e-post till [email protected].