SO4AG je otevřený formát pro firemní údaje: každý údaj nese svůj význam, rozsah platnosti, původ a dobu platnosti. Čtečka odpovídá na jednu otázku: smí se tento údaj použít pro tento úkol v tuto chvíli, a když ne, proč.
Formát je zdarma a nepotřebuje účet. Kód je pod licencí Apache-2.0, text specifikace pod CC BY 4.0.
Repozitář na GitHubu · specifikace · JSON Schema · testovací sada · JSON-LD · validátor v prohlížeči · co funguje
Obsah: 1. Stáhnout · 2. Ověřit zdroj · 3. Zeptat se na údaj · 4. Zveřejnit vlastní zdroj · 5. API · 6. MCP · 7. Vlastní čtečka · Jakýkoli obor · Kde projekt najdete
Potřebujete Git a Node.js 20 nebo novější. Čtečka v Pythonu vystačí se standardní knihovnou (Python 3.10 nebo novější).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
Poslední příkaz spustí testy referenčního kódu proti testovací sadě. Všechny mají projít.
Do vlastního projektu si balíčky nainstalujete jedním příkazem:
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 čte soubor nebo adresu. Rozumí zápisu SO4AG JSON, podobě JSON-LD i stránce HTML, která má JSON-LD v sobě.
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
Odpověď začíná slovem VALID nebo INVALID. U neplatného zdroje následuje seznam chyb s místem v souboru. Bez instalace jde totéž ve validátoru v prohlížeči.
Platný zdroj dokládá jen správnou stavbu. Neříká, že je údaj pravdivý.
Úkol říká, na kterou vlastnost se ptáte a pro jaké podmínky (rozsah). Čtečka vrátí každý odpovídající údaj s odpovědí, zda je použitelný, a s důvody, když není.
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
Zkuste totéž bez podmínky pobočky nebo s jiným časem (--now 2027-06-01T12:00:00Z, v JavaScriptu třetí argument { now: new Date(…) }). Údaj přestane být použitelný a čtečka řekne proč.
| Důvod | Co znamená |
|---|---|
expired, not_yet_valid | Údaj v čase otázky neplatí. |
scope_mismatch:<key> | Údaj platí pro jinou hodnotu podmínky, například pro jinou pobočku. |
scope_not_in_task:<key> | Údaj je omezený podmínkou, kterou úkol neuvádí. Bez ní se nedá říct, zda platí. |
unknown, not_applicable | Vydavatel výslovně uvádí, že hodnotu nezná nebo že se ho netýká. Neznámé není nula. |
disputed | Údaj je rozporovaný. |
no_trust_policy | Úkol žádá ověřený údaj, ale neříká, komu důvěřuje. Komu věřit, rozhoduje ten, kdo údaj čte. |
attestation_not_authenticated | Ve zdroji je potvrzení se jménem ověřovatele, kterému věříte, ale vy jste si ho u ověřovatele neověřili. Jméno napsané ve zdroji není důkaz. |
conflicting_claims | Dva platné údaje uvádějí pro totéž různé hodnoty. Čtečka nepoužije žádný a nevybírá potichu vítěze. |
invalid_source | Zdroj porušuje stavbu formátu (například údaj bez podkladu nebo nečitelné datum). Nepoužije se z něj nic. |
unsupported_version | Zdroj je ve verzi formátu, kterou čtečka nezná. Nečte ho podle pravidel jiné verze. |
Úplný seznam důvodů a pravidel je v specifikaci.
Zdroj je jeden soubor JSON. Nejmenší užitečná podoba má vydavatele a jeden údaj:
{
"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 ověřte ho validátorem (krok 2)./so4ag.json s typem application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. Převod je bezeztrátový.
node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) a před jeho uplynutím údaj potvrďte nebo změňte. Po tomto čase ho čtečky přestanou používat.Formát není vázaný na obor. Vlastnosti (co údaj znamená, jaký má typ a jednotku a jakými podmínkami se omezuje) určuje profil a zdroj jich může použít několik najednou.
| Profil | Pro koho |
|---|---|
| Obecný | Každá firma a organizace: provozovatel, provozovny a otevírací doba, kontakty, jazyky, co nabízí a za kolik, platby, objednání předem, doba odpovědi a dodání, storno, záruka, přístupnost, oprávnění, dostupnost. 26 vlastností. |
| Pronájem vozidel, Obchod | To, co je pro obor zvláštní: kauce, limit kilometrů, doprava, vrácení zboží. |
| Váš vlastní | Cokoli dalšího. Profil je soubor JSON na vaší doméně; nikoho se neptáte a nic neregistrujete. |
Vlastní profil popisuje vaše vlastnosti stejně jako naše profily: název, popis, typ hodnoty, jednotky, povolené kódy a podmínky. Nejmenší 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 tu adresu přidejte ve zdroji do pole profiles.namespace + název, tedy 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Čtečka, která váš profil nezná, údaj přesto použije, pokud úkol jeho podmínky uvede; když je neuvede, údaj nepoužije. Bezpečnostní pravidla formátu tedy platí pro všechny profily stejně. Úplný příklad zubní ordinace s obecným i vlastním profilem je v repozitáři: general-dental.json. Schéma profilu: profile.schema.json.
Nechcete soubor psát ručně? Služba SOQVER připraví návrh z vašeho webu, vy údaje potvrdíte a zdroj zveřejníte u nás nebo si ho stáhnete pro vlastní doménu: připravit zdroj.
Rozhraní je jen pro čtení a nepotřebuje účet ani klíč.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
První adresa vrátí seznam zdrojů, které firma zveřejnila nebo potvrdila. Druhá vyhodnotí údaje jednoho zdroje pro váš úkol a u každého vrátí usable a reasons. Každý zdroj je také stránka pro lidi (/s/<slug>/), soubor /s/<slug>/so4ag.json a podoba JSON-LD /s/<slug>/facts.jsonld.
Server MCP je jen pro čtení, bez účtu, s přenosem Streamable HTTP. V oficiálním registru MCP je zapsaný jako com.soqver/so4ag.
https://soqver.com/mcp
| Nástroj | Co dělá |
|---|---|
list_sources | Vypíše zveřejněné zdroje. |
get_source | Vrátí celý zdroj jedné firmy. |
get_claims | Vyhodnotí údaje zdroje pro zadanou vlastnost a podmínky. |
check_claim | Řekne, zda se jeden údaj smí teď použít, a proč ne. |
V klientovi, který umí vzdálené servery MCP, zadejte adresu výše. Odpověď serveru si ověříte i z příkazové řádky:
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"}'
Testovací sada je obyčejný JSON a nepotřebuje náš kód. Obsahuje dva platné zdroje ve třech podobách, očekávané otisky údajů, 45 případů vyhodnocení, 31 případů ověření, 10 případů celého zdroje a 25 vzorů kanonického zápisu (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Kdy čtečka nebo validátor sadou prochází, popisuje popis testovací sady. Čtečka v Pythonu je napsaná nezávisle na referenčním kódu a prochází stejnou sadou, můžete ji použít jako vzor.
| Místo | K čemu je |
|---|---|
| GitHub: soqvercom/so4ag | Kód, specifikace, testovací sada a vydání. Tady se formát vyvíjí. |
| Diskuse na GitHubu | Místo pro komunitu: otázky, návrhy a zkušenosti s formátem. Odpovídáme tady. |
| Hlášení na GitHubu | Chyby ve specifikaci a v kódu, případy, které formát neumí zapsat. |
| PyPI: so4ag | Balíček pro Python: pip install so4ag |
| Vydání | Balíček pro JavaScript a soubory každé verze: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Trvalý odkaz na vydání pro citace v článcích a dokumentaci. |
| Registr MCP | Záznam našeho serveru MCP: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Rychlé otázky a rozhovor s ostatními, kdo formát zkoušejí. |
| DEV: @soqvercom | Technické články a návody k formátu. |
| daily.dev: @soqver | Odkazy na nové články pro vývojáře. |
| X · YouTube | Novinky o formátu a krátké ukázky. |
Narazili jste na údaj, který formát neumí zapsat, nebo na dvě čtečky, které odpovídají různě? Napište to jako hlášení na GitHubu. Zranitelnost prosím hlaste e-mailem na [email protected].