SO4AG este un format deschis pentru faptele unei afaceri: fiecare fapt poartă semnificația, sfera de aplicare, originea și valabilitatea sa. Un cititor răspunde la o singură întrebare: poate fi utilizat acest fapt pentru această sarcină în acest moment și, dacă nu, de ce nu.
Formatul este gratuit și nu necesită cont. Codul este licențiat sub Apache-2.0, iar textul specificației sub CC BY 4.0.
Repozitoriu pe GitHub · specificație · JSON Schema · suită de conformitate · JSON-LD · validator în browser · ce funcționează
Cuprins: 1. Obțineți codul · 2. Validați o sursă · 3. Întrebați despre un fapt · 4. Publicați propria sursă · 5. API · 6. MCP · 7. Propriul cititor · Orice industrie · Unde găsiți proiectul
Aveți nevoie de Git și Node.js 20 sau mai nou. Cititorul Python necesită doar biblioteca standard (Python 3.10 sau mai nou).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
Ultima comandă execută testele codului de referință pe suita de conformitate. Toate ar trebui să treacă.
În propriul proiect, pachetele se instalează fiecare cu o singură comandă:
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
Validatorul citește un fișier sau o adresă. Înțelege JSON SO4AG, forma JSON-LD și o pagină HTML cu JSON-LD în interior.
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
Răspunsul începe cu VALID sau INVALID. Pentru o sursă nevalidă urmează o listă de erori, cu locul lor în fișier. Fără a instala nimic, același lucru funcționează în validatorul din browser.
O sursă validă dovedește doar structura corectă. Nu spune că faptul este adevărat.
O sarcină indică proprietatea despre care întrebați și pentru ce condiții (sferă de aplicare). Cititorul returnează fiecare afirmație corespunzătoare, cu răspunsul dacă este utilizabilă și cu motivele atunci când nu este.
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
Încercați același lucru fără condiția de sucursală sau la un alt moment (--now 2027-06-01T12:00:00Z, în JavaScript al treilea argument { now: new Date(…) }). Afirmația încetează să fie utilizabilă, iar cititorul spune de ce.
| Motiv | Ce înseamnă |
|---|---|
expired, not_yet_valid | Afirmația nu este valabilă la momentul întrebării. |
scope_mismatch:<key> | Afirmația este valabilă pentru o altă valoare a condiției, de exemplu o altă sucursală. |
scope_not_in_task:<key> | Afirmația este limitată de o condiție pe care sarcina nu o precizează. Fără ea, nimeni nu poate spune dacă afirmația se aplică. |
unknown, not_applicable | Editorul precizează explicit că valoarea nu este cunoscută sau nu se aplică. Necunoscut nu este zero. |
disputed | Afirmația este contestată. |
no_trust_policy | Sarcina cere o afirmație revizuită, dar nu precizează în cine are încredere. În cine să aibă încredere este decizia celui care citește afirmația. |
attestation_not_authenticated | Sursa conține o atestare cu numele unui emitent în care aveți încredere, dar nu ați autentificat-o la emitent. Un nume scris în sursă nu este o dovadă. |
conflicting_claims | Două afirmații curente indică valori diferite pentru același lucru. Cititorul nu folosește niciuna și nu alege niciodată în tăcere un câștigător. |
invalid_source | Sursa încalcă structura formatului (de exemplu o afirmație fără dovezi sau o dată ilizibilă). Nu se utilizează nimic din ea. |
unsupported_version | Sursa este într-o versiune a formatului pe care cititorul nu o cunoaște. Nu este citită după regulile altei versiuni. |
Lista completă a motivelor și a regulilor se află în specificație.
O sursă este un fișier JSON. Cea mai mică formă utilă are un editor și o afirmație:
{
"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 și verificați-l cu validatorul (pasul 2)./so4ag.json, cu tipul application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. Conversia este fără pierderi. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) și confirmați sau modificați afirmația înainte ca acesta să treacă. După acel moment, cititorii încetează să o utilizeze.Formatul nu este legat de o industrie. Proprietățile (ce înseamnă un fapt, tipul și unitatea sa și ce condiții îl limitează) sunt stabilite de un profil, iar o sursă poate folosi mai multe profiluri împreună.
| Profil | Pentru cine |
|---|---|
| General | Orice afacere sau organizație: operator, locații și program, contacte, limbi, ce oferă și la ce preț, plată, rezervare, timpi de răspuns și de livrare, anulare, garanție, accesibilitate, licențe, disponibilitate. 26 de proprietăți. |
| Închiriere de vehicule, Comerț cu amănuntul | Ce este specific industriei: depozit, limită de kilometraj, livrare, returnări. |
| Al dumneavoastră | Orice altceva. Un profil este un fișier JSON pe domeniul dumneavoastră; nu întrebați pe nimeni și nu înregistrați nimic. |
Profilul propriu descrie proprietățile dumneavoastră la fel ca ale noastre: etichetă, descriere, tip de valoare, unități, coduri permise și condiții. Forma minimă:
{
"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 și adăugați acea adresă în profiles din sursa dumneavoastră.namespace + nume, adică 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.jsonUn cititor care nu cunoaște profilul dumneavoastră folosește totuși afirmația atunci când sarcina îi precizează condițiile; când sarcina nu le precizează, afirmația nu este folosită. Regulile de siguranță ale formatului se aplică așadar la fel pentru fiecare profil. Un exemplu complet de cabinet stomatologic cu profilul General și cu profilul propriu se află în depozit: general-dental.json. Schema unui profil: profile.schema.json.
Preferați să nu scrieți fișierul manual? Serviciul SOQVER pregătește o propunere pornind de la site-ul dumneavoastră; confirmați faptele și publicați sursa la noi sau o descărcați pentru propriul domeniu: pregătiți o sursă.
Interfața este doar pentru citire și nu necesită nici cont, nici cheie.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
Prima adresă returnează lista surselor pe care o companie le-a publicat sau confirmat. A doua evaluează afirmațiile unei surse pentru sarcina dumneavoastră și returnează usable și reasons pentru fiecare. Fiecare sursă este totodată o pagină pentru persoane (/s/<slug>/), un fișier /s/<slug>/so4ag.json și o formă JSON-LD /s/<slug>/facts.jsonld.
Serverul MCP este doar pentru citire, nu necesită cont și folosește transportul Streamable HTTP. În MCP Registry oficial este listat ca com.soqver/so4ag.
https://soqver.com/mcp
| Instrument | Ce face |
|---|---|
list_sources | Listează sursele publicate. |
get_source | Returnează întreaga sursă a unei afaceri. |
get_claims | Evaluează afirmațiile unei surse pentru o proprietate și condiții date. |
check_claim | Indică dacă o afirmație poate fi folosită acum și de ce nu. |
Într-un client care acceptă servere MCP la distanță, introduceți adresa de mai sus. Puteți verifica răspunsul serverului și din linia de comandă:
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"}'
Suita de conformitate este JSON simplu și nu necesită niciun cod de-al nostru. Conține două surse valide în trei forme, digesturile așteptate ale afirmațiilor, 45 de cazuri de evaluare, 31 de cazuri de validare, 10 cazuri pentru sursa întreagă și 25 de vectori ai formei canonice (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Condițiile în care un cititor sau un validator trece suita sunt descrise în descrierea suitei de conformitate. Cititorul Python a fost scris independent de codul de referință și trece aceeași suită; îl puteți folosi drept model.
| Loc | La ce servește |
|---|---|
| GitHub: soqvercom/so4ag | Codul, specificația, suita de conformitate și versiunile. Aici se dezvoltă formatul. |
| GitHub Discussions | Locul comunității: întrebări, propuneri și experiența cu formatul. Răspundem aici. |
| GitHub Issues | Erori din specificație și din cod, cazuri pe care formatul nu le poate exprima. |
| PyPI: so4ag | Pachetul Python: pip install so4ag |
| Versiuni | Pachetul JavaScript și fișierele fiecărei versiuni: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Un link permanent către versiuni, pentru citare în articole și documentație. |
| MCP Registry | Înregistrarea serverului nostru MCP: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Întrebări rapide și o discuție cu alții care încearcă formatul. |
| DEV: @soqvercom | Articole tehnice și ghiduri despre format. |
| daily.dev: @soqver | Legături către articole noi pentru dezvoltatori. |
| X · YouTube | Știri despre format și demonstrații scurte. |
Ați găsit un fapt pe care formatul nu îl poate exprima sau doi cititori care răspund diferit? Scrieți-l ca problemă pe GitHub. Vă rugăm să raportați o vulnerabilitate prin e-mail la [email protected].