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.
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
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
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ý.
Ú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.
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
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_valid | Tvrdenie 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_applicable | Vydavateľ výslovne uvádza, že hodnota nie je známa alebo sa neuplatňuje. Neznáme nie je nula. |
disputed | Tvrdenie 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_authenticated | Zdroj 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_claims | Dve aktuálne tvrdenia uvádzajú odlišné hodnoty tej istej veci. Čitateľ nepoužíva ani jedno a víťaza nikdy nevyberá mlčky. |
invalid_source | Zdroj 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_version | Zdroj 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.
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"
}
]
}
so4ag.json a skontrolujte ho validátorom (krok 2)./so4ag.json s typom application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. Prevod je bezstratový. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) a tvrdenie potvrďte alebo zmeňte skôr, ako uplynie. Po tomto čase ho čítače prestanú používať.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.
| Profil | Pre 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."
}
}
}
id a túto adresu pridajte do profiles vo svojom zdroji.namespace + názov, teda 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.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.
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.
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_sources | Vypíše zverejnené zdroje. |
get_source | Vráti celý zdroj jednej firmy. |
get_claims | Vyhodnotí tvrdenia zdroja pre danú vlastnosť a podmienky. |
check_claim | Povie, č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"}'
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.
| Miesto | Na čo slúži |
|---|---|
| GitHub: soqvercom/so4ag | Kód, špecifikácia, sada testov zhody a vydania. Tu sa formát vyvíja. |
| GitHub Discussions | Miesto pre komunitu: otázky, návrhy a skúsenosti s formátom. Tu odpovedáme. |
| GitHub Issues | Chyby v špecifikácii a v kóde, prípady, ktoré formát nedokáže vyjadriť. |
| PyPI: so4ag | Balík Python: pip install so4ag |
| Vydania | Balí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 Registry | Záznam nášho servera MCP: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Rýchle otázky a rozhovor s ostatnými, ktorí formát skúšajú. |
| DEV: @soqvercom | Technické články a návody o formáte. |
| daily.dev: @soqver | Odkazy na nové články pre vývojárov. |
| X · YouTube | Novinky o formáte a krátke ukážky. |
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].