A SO4AG az üzleti tények nyílt formátuma: minden tény hordozza a jelentését, a hatókörét, az eredetét és az érvényességét. Az olvasó egy kérdésre válaszol: felhasználható-e ez a tény ehhez a feladathoz ebben az időpontban, és ha nem, miért nem.
A formátum ingyenes, és nem igényel fiókot. A kód Apache-2.0, a specifikáció szövege CC BY 4.0 licenc alatt áll.
Tároló a GitHubon · specifikáció · JSON Schema · megfelelőségi tesztkészlet · JSON-LD · ellenőrző a böngészőben · mi működik
Tartalom: 1. A kód beszerzése · 2. Egy forrás érvényesítése · 3. Kérdés egy tényről · 4. Saját forrás közzététele · 5. API · 6. MCP · 7. Saját olvasó · Bármely iparág · Hol található a projekt
Gitre és Node.js 20-ra vagy újabbra van szüksége. A Python-olvasó csak a szabványos könyvtárat igényli (Python 3.10 vagy újabb).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
Az utolsó parancs a referenciakód tesztjeit futtatja a megfelelőségi tesztkészleten. Mindegyiknek át kell mennie.
A csomagok a saját projektbe egy-egy paranccsal települnek:
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
Az ellenőrző fájlt vagy címet olvas. Érti a SO4AG JSON-t, a JSON-LD formát és azt a HTML-oldalt, amelyben a JSON-LD található.
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
A válasz a VALID vagy az INVALID szóval kezdődik. Érvénytelen forrás esetén a hibák listája következik, a fájlbeli helyükkel. Telepítés nélkül ugyanez működik a böngészős ellenőrzőben.
Az érvényes forrás csak a helyes szerkezetet igazolja. Nem állítja, hogy a tény igaz.
A feladat megmondja, melyik tulajdonságra kérdez, és milyen feltételek (hatókör) mellett. Az olvasó minden illeszkedő állítást visszaad, azzal a válasszal, hogy felhasználható-e, és az okokkal, ha nem.
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
Próbálja ki ugyanezt a fiókfeltétel nélkül vagy más időpontban (--now 2027-06-01T12:00:00Z, JavaScriptben a harmadik argumentum { now: new Date(…) }). Az állítás nem lesz felhasználható, és az olvasó megmondja, miért.
| Ok | Mit jelent |
|---|---|
expired, not_yet_valid | Az állítás a kérdés időpontjában nem áll fenn. |
scope_mismatch:<key> | Az állítás a feltétel másik értékére áll fenn, például egy másik fiókra. |
scope_not_in_task:<key> | Az állítást olyan feltétel korlátozza, amelyet a feladat nem ad meg. Enélkül senki sem mondhatja meg, hogy az állítás vonatkozik-e. |
unknown, not_applicable | A közzétevő kifejezetten kijelenti, hogy az érték nem ismert, vagy nem alkalmazható. Az ismeretlen nem nulla. |
disputed | Az állítás vitatott. |
no_trust_policy | A feladat felülvizsgált állítást kér, de nem mondja meg, kiben bízik. Hogy kiben bízik, arról az dönt, aki az állítást olvassa. |
attestation_not_authenticated | A forrás olyan igazolást hordoz, amely egy Ön által megbízhatónak tartott kibocsátó nevét tartalmazza, Ön azonban azt a kibocsátónál nem hitelesítette. A forrásba írt név nem bizonyíték. |
conflicting_claims | Két aktuális állítás ugyanarra a dologra eltérő értéket ad meg. Az olvasó egyiket sem használja, és soha nem választ csendben győztest. |
invalid_source | A forrás megsérti a formátum szerkezetét (például bizonyíték nélküli állítás vagy olvashatatlan dátum). Belőle semmi sem kerül felhasználásra. |
unsupported_version | A forrás a formátum olyan verziójú, amelyet az olvasó nem ismer. Nem egy másik verzió szabályai szerint olvassa be. |
Az okok és a szabályok teljes listája a specifikációban található.
A forrás egyetlen JSON-fájl. A legkisebb használható forma egy közzétevőt és egy állítást tartalmaz:
{
"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 néven, és ellenőrizze az ellenőrzővel (2. lépés)./so4ag.json címen, application/json típussal.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json"> címkébe. Az átalakítás veszteségmentes. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until), és mielőtt ez elmúlik, erősítse meg vagy módosítsa az állítást. Ezután az olvasók nem használják.A formátum nem kötődik egy iparághoz. A tulajdonságokat (mit jelent egy tény, milyen a típusa és a mértékegysége, és mely feltételek korlátozzák) egy profil határozza meg, és egy forrás több profilt együtt is használhat.
| Profil | Kinek |
|---|---|
| General | Bármely vállalkozás vagy szervezet: üzemeltető, helyek és nyitvatartás, elérhetőségek, nyelvek, mit kínál és mennyiért, fizetés, foglalás, válaszadási és szállítási idők, lemondás, garancia, akadálymentesség, engedélyek, rendelkezésre állás. 26 tulajdonság. |
| Gépjárműbérlés, Kiskereskedelem | Ami az iparágra jellemző: kaució, kilométerkorlát, szállítás, visszáru. |
| Saját | Bármi más. A profil egy JSON-fájl az Ön domainjén; senkitől nem kell engedélyt kérnie, és semmit nem kell regisztrálnia. |
A saját profilja ugyanúgy írja le a tulajdonságait, ahogyan a mieink: címke, leírás, értéktípus, mértékegységek, megengedett kódok és feltételek. A legrövidebb forma:
{
"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 helyen megadott címen, és adja hozzá ezt a címet a forrásában a profiles elemhez.namespace + név, azaz 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.jsonAz az olvasó, amely nem ismeri az Ön profilját, akkor is felhasználja az állítást, ha a feladat megadja a feltételeit; ha a feladat nem adja meg, az állítást nem használja. A formátum biztonsági szabályai ezért minden profilra egyaránt érvényesek. Egy fogorvosi rendelő teljes példája a General profillal és a saját profiljával a repozitóriumban található: general-dental.json. Egy profil sémája: profile.schema.json.
Inkább nem írná meg a fájlt kézzel? A SOQVER szolgáltatás a webhelye alapján javaslatot készít, Ön megerősíti a tényeket, és nálunk teszi közzé a forrást, vagy letölti a saját domainjére: forrás előkészítése.
A felület csak olvasható, és nem igényel fiókot vagy kulcsot.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
Az első cím azon források listáját adja vissza, amelyeket egy vállalat közzétett vagy megerősített. A második egy forrás állításait értékeli az Ön feladata szerint, és mindegyikhez usable és reasons értéket ad vissza. Minden forrás egyúttal embereknek szóló oldal (/s/<slug>/), fájl /s/<slug>/so4ag.json és JSON-LD forma /s/<slug>/facts.jsonld is.
Az MCP-kiszolgáló csak olvasható, nem igényel fiókot, és a Streamable HTTP átvitelt használja. A hivatalos MCP Registryben com.soqver/so4ag néven szerepel.
https://soqver.com/mcp
| Eszköz | Mit végez |
|---|---|
list_sources | A közzétett forrásokat listázza. |
get_source | Egy vállalkozás teljes forrását adja vissza. |
get_claims | Egy forrás állításait értékeli adott tulajdonság és feltételek szerint. |
check_claim | Megmondja, hogy egy állítás most felhasználható-e, és ha nem, miért. |
Távoli MCP-kiszolgálókat támogató kliensben adja meg a fenti címet. A kiszolgáló válaszát a parancssorból is ellenőrizheti:
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"}'
A megfelelőségi készlet sima JSON, és a kódunkra nincs szüksége. Két érvényes forrást tartalmaz három formában, az állítások várt lenyomatait, 45 kiértékelési esetet, 31 érvényesítési esetet, 10 teljes forrásra vonatkozó esetet és a kanonikus forma 25 vektorát (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Azt, hogy egy olvasó vagy egy ellenőrző mikor felel meg a készletnek, a megfelelőségi készlet leírása ismerteti. A Python-olvasó a referenciakódtól függetlenül készült, és ugyanezen a készleten megfelel; mintaként használhatja.
| Hely | Mire való |
|---|---|
| GitHub: soqvercom/so4ag | Kód, specifikáció, megfelelőségi tesztkészlet és kiadások. A formátumot itt fejlesztjük. |
| GitHub Discussions | A közösség helye: kérdések, javaslatok és a formátummal szerzett tapasztalatok. Itt válaszolunk. |
| GitHub Issues | A specifikáció és a kód hibái, valamint a formátummal ki nem fejezhető esetek. |
| PyPI: so4ag | A Python-csomag: pip install so4ag |
| Kiadások | A JavaScript-csomag és az egyes verziók fájljai: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Állandó hivatkozás a kiadásokra, szakcikkekben és dokumentációban való idézéshez. |
| MCP Registry | Az MCP-szerverünk bejegyzése: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Gyors kérdések és beszélgetés másokkal, akik kipróbálják a formátumot. |
| DEV: @soqvercom | Technikai cikkek és gyakorlati útmutatók a formátumról. |
| daily.dev: @soqver | Hivatkozások új cikkekre fejlesztőknek. |
| X · YouTube | Hírek a formátumról és rövid bemutatók. |
Olyan tényt talált, amelyet a formátum nem tud kifejezni, vagy két olvasót, amelyek eltérően válaszolnak? Írja meg issue-ként a GitHubon. A sebezhetőséget kérjük, e-mailben jelentse a [email protected] címen.