SOQVER Pripraviť zdroj
Slovenčina

Príručka pre vývojárov

SO4AG je otvorený formát pre firemné fakty: každý fakt nesie svoj význam, rozsah, pôvod a platnosť. Čítač odpovedá na jednu otázku: smie sa tento fakt použiť na túto úlohu v tomto čase, a ak nie, prečo nie.

Formát je bezplatný a nevyžaduje účet. Kód je licencovaný pod Apache-2.0, text špecifikácie pod CC BY 4.0.

Všetko na jednom mieste

Repozitár na GitHub · špecifikácia · JSON Schema · sada zhody · JSON-LD · validátor v prehliadači · čo funguje

Obsah: 1. Získajte kód · 2. Overte zdroj · 3. Opýtajte sa na fakt · 4. Zverejnite vlastný zdroj · 5. API · 6. MCP · 7. Vlastný čítač · Ľubovoľné odvetvie · Kde nájdete projekt

1. Získajte kód

Potrebujete Git a Node.js 20 alebo novší. Čítač v jazyku Python potrebuje len štandardnú knižnicu (Python 3.10 alebo novší).

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

Posledný príkaz spúšťa testy referenčného kódu voči sade zhody. Všetky by mali prejsť.

Do vlastného projektu sa každý balík nainštaluje jedným príkazom:

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

Validátor číta súbor alebo adresu. Rozumie formátu SO4AG JSON, podobe JSON-LD aj stránke HTML s JSON-LD vnútri.

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

Odpoveď začína slovami VALID alebo INVALID. Pri neplatnom zdroji nasleduje zoznam chýb s ich miestom v súbore. Bez akejkoľvek inštalácie to isté funguje vo validátore v prehliadači.

Platný zdroj dokazuje iba správnu štruktúru. Nehovorí, že fakt je pravdivý.

3. Opýtajte sa, či sa skutočnosť môže použiť

Úloha uvádza, na ktorú vlastnosť sa pýtate a za akých podmienok (rozsah). Čítač vráti každý zodpovedajúci výrok s odpoveďou, či je použiteľný, a s dôvodmi, keď nie je.

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

Vyskúšajte to isté bez podmienky pobočky alebo v inom čase (--now 2027-06-01T12:00:00Z, v jazyku JavaScript tretí argument { now: new Date(…) }). Tvrdenie prestane byť použiteľné a čítač povie prečo.

DôvodČo to znamená
expired, not_yet_validTvrdenie v čase otázky neplatí.
scope_mismatch:<key>Tvrdenie platí pre inú hodnotu podmienky, napríklad pre inú pobočku.
scope_not_in_task:<key>Tvrdenie obmedzuje podmienka, ktorú úloha neuvádza. Bez nej nikto nemôže povedať, či sa tvrdenie vzťahuje.
unknown, not_applicableVydavateľ výslovne uvádza, že hodnota nie je známa alebo sa neuplatňuje. Neznáme nie je nula.
disputedTvrdenie je sporné.
no_trust_policyÚloha žiada preskúmané tvrdenie, ale neuvádza, komu dôveruje. Komu dôverovať, je rozhodnutie toho, kto tvrdenie číta.
attestation_not_authenticatedZdroj obsahuje atestáciu s menom vydavateľa, ktorému dôverujete, ale neautentifikovali ste ju u vydavateľa. Meno zapísané v zdroji nie je dôkaz.
conflicting_claimsDve aktuálne tvrdenia uvádzajú odlišné hodnoty tej istej veci. Čitateľ nepoužíva ani jedno a víťaza nikdy nevyberá mlčky.
invalid_sourceZdroj porušuje štruktúru formátu (napríklad tvrdenie bez dôkazu alebo nečitateľný dátum). Nič z neho sa nepoužíva.
unsupported_versionZdroj je vo verzii formátu, ktorú čítač nepozná. Nečíta sa podľa pravidiel inej verzie.

Úplný zoznam dôvodov a pravidiel je v špecifikácii.

4. Zverejnite vlastný zdroj

Zdroj je jeden súbor JSON. Najmenšia užitočná podoba má vydavateľa a jedno tvrdenie:

{
  "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. Uložte súbor ako so4ag.json a skontrolujte ho validátorom (krok 2).
  2. Poskytujte ho cez HTTPS na svojej doméne na adrese /so4ag.json s typom application/json.
  3. Pridajte odkaz na zdroj na stránky pre ľudí:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Ak chcete mať tie isté fakty vo vnútri stránky, preveďte zdroj do JSON-LD a výsledok vložte do značky <script type="application/ld+json">. Prevod je bezstratový.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Každému tvrdeniu určte koniec platnosti (valid_until) a tvrdenie potvrďte alebo zmeňte skôr, ako uplynie. Po tomto čase ho čítače prestanú používať.

Ľubovoľné odvetvie: všeobecný profil a váš vlastný profil

Formát nie je viazaný na odvetvie. Vlastnosti (čo fakt znamená, jeho typ a jednotku a ktoré podmienky ho obmedzujú) určuje profil a jeden zdroj môže používať viacero profilov naraz.

ProfilPre koho
VšeobecnýĽubovoľný podnik alebo organizácia: prevádzkovateľ, miesta a otváracie hodiny, kontakty, jazyky, čo ponúka a za koľko, platba, rezervácia, časy odpovede a doručenia, zrušenie, záruka, prístupnosť, licencie, dostupnosť. 26 vlastností.
Prenájom vozidiel, MaloobchodČo je špecifické pre odvetvie: záloha, limit najazdených kilometrov, doprava, vrátenie tovaru.
Váš vlastnýČokoľvek ďalšie. Profil je súbor JSON na vašej doméne; nikoho nežiadate a nič neregistrujete.

Váš vlastný profil opisuje vaše vlastnosti rovnako ako tie naše: označenie, opis, typ hodnoty, jednotky, povolené kódy a podmienky. Najmenšia podoba:

{
  "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. Sprístupnite súbor cez HTTPS na adrese uvedenej v id a túto adresu pridajte do profiles vo svojom zdroji.
  2. Vlastnosť tvrdenia zapíšte ako namespace + názov, teda https://dental.example/so4ag-profile#emergencySlot.
  3. Skontrolujte profil a zdroj:
    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

Čítač, ktorý váš profil nepozná, tvrdenie aj tak použije, keď úloha uvádza jeho podmienky; keď ich úloha neuvádza, tvrdenie sa nepoužije. Bezpečnostné pravidlá formátu preto platia pre každý profil rovnako. Úplný príklad zubnej ambulancie so všeobecným profilom a vlastným profilom je v repozitári: general-dental.json. Schéma profilu: profile.schema.json.

Nechcete súbor písať ručne? Služba SOQVER pripraví návrh z vašej webovej stránky, vy fakty potvrdíte a zdroj zverejníte u nás alebo si ho stiahnete pre vlastnú doménu: pripraviť zdroj.

5. Čítajte zverejnené zdroje cez API

Rozhranie je len na čítanie a nevyžaduje účet ani kľúč.

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

Prvá adresa vráti zoznam zdrojov, ktoré firma zverejnila alebo potvrdila. Druhá vyhodnotí tvrdenia jedného zdroja pre vašu úlohu a pre každé vráti usable a reasons. Každý zdroj je zároveň stránkou pre ľudí (/s/<slug>/), súborom /s/<slug>/so4ag.json a podobou JSON-LD /s/<slug>/facts.jsonld.

6. Pripojte agenta cez MCP

Server MCP je len na čítanie, nevyžaduje účet a používa prenos Streamable HTTP. V oficiálnom MCP Registry je uvedený ako com.soqver/so4ag.

https://soqver.com/mcp
NástrojČo robí
list_sourcesVypíše zverejnené zdroje.
get_sourceVráti celý zdroj jednej firmy.
get_claimsVyhodnotí tvrdenia zdroja pre danú vlastnosť a podmienky.
check_claimPovie, či sa jedno tvrdenie teraz môže použiť, a prečo nie.

V klientovi, ktorý podporuje vzdialené servery MCP, zadajte adresu vyššie. Odpoveď servera môžete overiť aj z príkazového riadka:

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. Napíšte vlastný čítač

Sada zhody je obyčajný JSON a nepotrebuje žiadny náš kód. Obsahuje dva platné zdroje v troch podobách, očakávané odtlačky tvrdení, 45 prípadov vyhodnotenia, 31 prípadov validácie, 10 prípadov celého zdroja a 25 vektorov kanonickej formy (RFC 8785).

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

Kedy čítač alebo validátor vyhovie sade, opisuje opis sady zhody. Čítač v jazyku Python bol napísaný nezávisle od referenčného kódu a vyhovuje tej istej sade; môžete ho použiť ako vzor.

Kde nájsť projekt

MiestoNa čo slúži
GitHub: soqvercom/so4agKód, špecifikácia, sada testov zhody a vydania. Tu sa formát vyvíja.
GitHub DiscussionsMiesto pre komunitu: otázky, návrhy a skúsenosti s formátom. Tu odpovedáme.
GitHub IssuesChyby v špecifikácii a v kóde, prípady, ktoré formát nedokáže vyjadriť.
PyPI: so4agBalík Python: pip install so4ag
VydaniaBalík JavaScript a súbory každej verzie: npm install github:soqvercom/so4ag
Zenodo (DOI)Trvalý odkaz na vydania na citovanie v článkoch a dokumentácii.
MCP RegistryZáznam nášho servera MCP: com.soqver/so4ag
Discord: SOQVER · SO4AGRýchle otázky a rozhovor s ostatnými, ktorí formát skúšajú.
DEV: @soqvercomTechnické články a návody o formáte.
daily.dev: @soqverOdkazy na nové články pre vývojárov.
X · YouTubeNovinky o formáte a krátke ukážky.

Spätná väzba a chyby

Našli ste skutočnosť, ktorú formát nedokáže vyjadriť, alebo dvoch čítačov, ktorí odpovedajú odlišne? Napíšte to ako hlásenie na GitHub. Zraniteľnosť nahláste e-mailom na [email protected].