SOQVER Pregătiți o sursă
Română

Ghid pentru dezvoltatori

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.

Totul într-un singur loc

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

1. Obțineți codul

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

2. Validați o sursă

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.

3. Întrebați dacă un fapt poate fi folosit

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.

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

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

MotivCe înseamnă
expired, not_yet_validAfirmaț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_applicableEditorul precizează explicit că valoarea nu este cunoscută sau nu se aplică. Necunoscut nu este zero.
disputedAfirmația este contestată.
no_trust_policySarcina 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_authenticatedSursa 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_claimsDouă 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_sourceSursa încalcă structura formatului (de exemplu o afirmație fără dovezi sau o dată ilizibilă). Nu se utilizează nimic din ea.
unsupported_versionSursa 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.

4. Publicați propria sursă

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"
    }
  ]
}
  1. Salvați fișierul ca so4ag.json și verificați-l cu validatorul (pasul 2).
  2. Serviți-o prin HTTPS pe domeniul dumneavoastră la /so4ag.json, cu tipul application/json.
  3. Adăugați o legătură către sursă în paginile pentru persoane:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Pentru a avea aceleași fapte în pagină, convertiți sursa în JSON-LD și puneți rezultatul într-o etichetă <script type="application/ld+json">. Conversia este fără pierderi.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Dați fiecărei afirmații un sfârșit al valabilității (valid_until) și confirmați sau modificați afirmația înainte ca acesta să treacă. După acel moment, cititorii încetează să o utilizeze.

Orice industrie: profilul General și profilul propriu

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

ProfilPentru cine
GeneralOrice 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ănuntulCe 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."
    }
  }
}
  1. Serviți fișierul prin HTTPS la adresa indicată în id și adăugați acea adresă în profiles din sursa dumneavoastră.
  2. Scrieți proprietatea unei afirmații ca namespace + nume, adică https://dental.example/so4ag-profile#emergencySlot.
  3. Verificați profilul și sursa:
    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

Un 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ă.

5. Citiți sursele publicate prin API

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.

6. Conectați un agent prin MCP

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
InstrumentCe face
list_sourcesListează sursele publicate.
get_sourceReturnează întreaga sursă a unei afaceri.
get_claimsEvaluează afirmațiile unei surse pentru o proprietate și condiții date.
check_claimIndică 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"}'

7. Scrieți propriul cititor

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.

Unde găsiți proiectul

LocLa ce servește
GitHub: soqvercom/so4agCodul, specificația, suita de conformitate și versiunile. Aici se dezvoltă formatul.
GitHub DiscussionsLocul comunității: întrebări, propuneri și experiența cu formatul. Răspundem aici.
GitHub IssuesErori din specificație și din cod, cazuri pe care formatul nu le poate exprima.
PyPI: so4agPachetul Python: pip install so4ag
VersiuniPachetul 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: @soqvercomArticole tehnice și ghiduri despre format.
daily.dev: @soqverLegături către articole noi pentru dezvoltatori.
X · YouTubeȘtiri despre format și demonstrații scurte.

Feedback și erori

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