SOQVER Připravit zdroj
Čeština

Návod pro vývojáře

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.

Vše na jednom místě

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

1. Stáhněte si kód

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

2. Ověřte zdroj

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

3. Zeptejte se, zda se údaj smí použít

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

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

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ůvodCo 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_applicableVydavatel 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_authenticatedVe 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_claimsDva platné údaje uvádějí pro totéž různé hodnoty. Čtečka nepoužije žádný a nevybírá potichu vítěze.
invalid_sourceZdroj porušuje stavbu formátu (například údaj bez podkladu nebo nečitelné datum). Nepoužije se z něj nic.
unsupported_versionZdroj 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.

4. Zveřejněte vlastní zdroj

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"
    }
  ]
}
  1. Uložte soubor jako so4ag.json a ověřte ho validátorem (krok 2).
  2. Vystavte ho přes HTTPS na své doméně na adrese /so4ag.json s typem application/json.
  3. Do stránek pro lidi přidejte odkaz na zdroj:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Chcete-li mít tytéž údaje přímo ve stránce, převeďte zdroj do JSON-LD a vložte výsledek do značky <script type="application/ld+json">. Převod je bezeztrátový.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Každému údaji dejte konec platnosti (valid_until) a před jeho uplynutím údaj potvrďte nebo změňte. Po tomto čase ho čtečky přestanou používat.

Jakýkoli obor: obecný profil a vlastní profil

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.

ProfilPro 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, ObchodTo, 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."
    }
  }
}
  1. Soubor vystavte přes HTTPS na adrese uvedené v id a tu adresu přidejte ve zdroji do pole profiles.
  2. Vlastnost v údaji zapište jako namespace + název, tedy https://dental.example/so4ag-profile#emergencySlot.
  3. Profil i zdroj zkontrolujte:
    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.

5. Čtěte zveřejněné zdroje přes API

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.

6. Připojte agenta přes MCP

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ástrojCo dělá
list_sourcesVypíše zveřejněné zdroje.
get_sourceVrátí celý zdroj jedné firmy.
get_claimsVyhodnotí ú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"}'

7. Napište vlastní čtečku

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.

Kde projekt najdete

MístoK čemu je
GitHub: soqvercom/so4agKód, specifikace, testovací sada a vydání. Tady se formát vyvíjí.
Diskuse na GitHubuMísto pro komunitu: otázky, návrhy a zkušenosti s formátem. Odpovídáme tady.
Hlášení na GitHubuChyby ve specifikaci a v kódu, případy, které formát neumí zapsat.
PyPI: so4agBalíč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 MCPZáznam našeho serveru MCP: com.soqver/so4ag
Discord: SOQVER · SO4AGRychlé otázky a rozhovor s ostatními, kdo formát zkoušejí.
DEV: @soqvercomTechnické články a návody k formátu.
daily.dev: @soqverOdkazy na nové články pro vývojáře.
X · YouTubeNovinky o formátu a krátké ukázky.

Připomínky a chyby

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