SOQVER Forrás előkészítése
Magyar

Útmutató fejlesztőknek

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.

Minden egy helyen

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

1. A kód beszerzése

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

2. Forrás ellenőrzése

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.

3. Kérdés arról, hogy egy tény felhasználható-e

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.

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

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.

OkMit jelent
expired, not_yet_validAz á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_applicableA közzétevő kifejezetten kijelenti, hogy az érték nem ismert, vagy nem alkalmazható. Az ismeretlen nem nulla.
disputedAz állítás vitatott.
no_trust_policyA 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_authenticatedA 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_claimsKé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_sourceA 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_versionA 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ó.

4. Saját forrás közzététele

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"
    }
  ]
}
  1. Mentse a fájlt so4ag.json néven, és ellenőrizze az ellenőrzővel (2. lépés).
  2. Szolgáltassa ki HTTPS-en a saját domainjén, a(z) /so4ag.json címen, application/json típussal.
  3. Adjon hivatkozást a forrásra az embereknek szóló oldalakon:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Ahhoz, hogy ugyanazok a tények az oldalon belül szerepeljenek, alakítsa át a forrást JSON-LD-re, és tegye az eredményt egy <script type="application/ld+json"> címkébe. Az átalakítás veszteségmentes.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Adjon minden állításnak érvényességi véget (valid_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.

Bármely iparág: a General profil és a saját profil

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.

ProfilKinek
GeneralBá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, KiskereskedelemAmi az iparágra jellemző: kaució, kilométerkorlát, szállítás, visszáru.
SajátBá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."
    }
  }
}
  1. Szolgáltassa a fájlt HTTPS-en a id helyen megadott címen, és adja hozzá ezt a címet a forrásában a profiles elemhez.
  2. Az állítás tulajdonságát így írja: namespace + név, azaz https://dental.example/so4ag-profile#emergencySlot.
  3. Ellenőrizze a profilt és a forrást:
    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

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

5. Közzétett források olvasása az API-n keresztül

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.

6. Ügynök csatlakoztatása MCP-n keresztül

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özMit végez
list_sourcesA közzétett forrásokat listázza.
get_sourceEgy vállalkozás teljes forrását adja vissza.
get_claimsEgy forrás állításait értékeli adott tulajdonság és feltételek szerint.
check_claimMegmondja, 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"}'

7. Saját olvasó írása

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.

Hol található a projekt

HelyMire való
GitHub: soqvercom/so4agKód, specifikáció, megfelelőségi tesztkészlet és kiadások. A formátumot itt fejlesztjük.
GitHub DiscussionsA közösség helye: kérdések, javaslatok és a formátummal szerzett tapasztalatok. Itt válaszolunk.
GitHub IssuesA specifikáció és a kód hibái, valamint a formátummal ki nem fejezhető esetek.
PyPI: so4agA Python-csomag: pip install so4ag
KiadásokA 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 RegistryAz MCP-szerverünk bejegyzése: com.soqver/so4ag
Discord: SOQVER · SO4AGGyors kérdések és beszélgetés másokkal, akik kipróbálják a formátumot.
DEV: @soqvercomTechnikai cikkek és gyakorlati útmutatók a formátumról.
daily.dev: @soqverHivatkozások új cikkekre fejlesztőknek.
X · YouTubeHírek a formátumról és rövid bemutatók.

Visszajelzés és hibá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.