SOQVER Przygotuj źródło
Polski

Przewodnik dla programistów

SO4AG to otwarty format faktów biznesowych: każdy fakt niesie swoje znaczenie, zakres, pochodzenie i ważność. Czytnik odpowiada na jedno pytanie: czy ten fakt może zostać użyty do tego zadania w tym czasie, a jeśli nie, to dlaczego.

Format jest bezpłatny i nie wymaga konta. Kod jest udostępniany na licencji Apache-2.0, a tekst specyfikacji na licencji CC BY 4.0.

Wszystko w jednym miejscu

Repozytorium na GitHub · specyfikacja · JSON Schema · zestaw zgodności · JSON-LD · walidator w przeglądarce · co działa

Spis treści: 1. Pobierz kod · 2. Zweryfikuj źródło · 3. Zapytaj o fakt · 4. Opublikuj własne źródło · 5. API · 6. MCP · 7. Własny czytnik · Dowolna branża · Gdzie znaleźć projekt

1. Pobierz kod

Potrzebują Państwo Git i Node.js 20 lub nowszego. Czytnik w języku Python wymaga tylko biblioteki standardowej (Python 3.10 lub nowszy).

git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test

Ostatnie polecenie uruchamia testy kodu referencyjnego względem zestawu zgodności. Wszystkie powinny przejść.

Do własnego projektu każdy pakiet instaluje się jednym poleceniem:

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. Zweryfikuj źródło

Walidator odczytuje plik lub adres. Rozpoznaje JSON SO4AG, postać JSON-LD oraz stronę HTML z osadzonym JSON-LD.

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

Odpowiedź zaczyna się od VALID lub INVALID. Przy nieprawidłowym źródle następuje lista błędów wraz z ich miejscem w pliku. Bez instalowania czegokolwiek to samo działa w walidatorze w przeglądarce.

Prawidłowe źródło potwierdza wyłącznie poprawną strukturę. Nie oznacza, że fakt jest prawdziwy.

3. Zapytaj, czy fakt można wykorzystać

Zadanie określa, o jaką właściwość Państwo pytają i przy jakich warunkach (zakres). Czytnik zwraca każde pasujące twierdzenie wraz z odpowiedzią, czy nadaje się do użycia, oraz z powodami, gdy się nie nadaje.

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

Proszę sprawdzić to samo bez warunku oddziału albo w innym czasie (--now 2027-06-01T12:00:00Z, w JavaScript trzeci argument { now: new Date(…) }). Twierdzenie przestaje nadawać się do użycia, a czytnik podaje dlaczego.

PowódZnaczenie
expired, not_yet_validTwierdzenie nie obowiązuje w chwili zadania pytania.
scope_mismatch:<key>Twierdzenie obowiązuje dla innej wartości warunku, na przykład dla innego oddziału.
scope_not_in_task:<key>Twierdzenie jest ograniczone warunkiem, którego zadanie nie podaje. Bez niego nie można stwierdzić, czy twierdzenie ma zastosowanie.
unknown, not_applicableWydawca wyraźnie stwierdza, że wartość nie jest znana albo nie ma zastosowania. Nieznane nie oznacza zera.
disputedTwierdzenie jest sporne.
no_trust_policyZadanie oczekuje twierdzenia po przeglądzie, ale nie wskazuje, komu ufa. O tym, komu ufać, decyduje ten, kto odczytuje twierdzenie.
attestation_not_authenticatedŹródło zawiera poświadczenie z nazwą wystawcy, któremu Państwo ufają, lecz nie uwierzytelnili go Państwo u wystawcy. Nazwa zapisana w źródle nie stanowi dowodu.
conflicting_claimsDwa aktualne twierdzenia podają różne wartości tej samej rzeczy. Czytelnik nie używa żadnego z nich i nigdy nie wybiera zwycięzcy po cichu.
invalid_sourceŹródło łamie strukturę formatu (na przykład twierdzenie bez dowodu albo nieczytelna data). Nic z niego nie jest używane.
unsupported_versionŹródło jest w wersji formatu, której czytnik nie zna. Nie odczytuje się go według reguł innej wersji.

Pełna lista powodów i reguł znajduje się w specyfikacji.

4. Opublikuj własne źródło

Źródło to jeden plik JSON. Najmniejsza użyteczna postać zawiera wydawcę i jedno twierdzenie:

{
  "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. Proszę zapisać plik jako so4ag.json i sprawdzić go walidatorem (krok 2).
  2. Proszę udostępnić je przez HTTPS we własnej domenie pod adresem /so4ag.json z typem application/json.
  3. Proszę dodać odnośnik do źródła na stronach dla ludzi:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Aby te same fakty znalazły się na stronie, proszę przekonwertować źródło do JSON-LD i umieścić wynik w znaczniku <script type="application/ld+json">. Konwersja jest bezstratna.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Proszę nadać każdemu twierdzeniu koniec ważności (valid_until) oraz potwierdzić je lub zmienić, zanim ten moment minie. Po tym czasie czytniki przestają z niego korzystać.

Dowolna branża: profil General i własny profil

Format nie jest związany z branżą. Właściwości (co oznacza fakt, jego typ i jednostka oraz które warunki go ograniczają) określa profil, a jedno źródło może korzystać z kilku profili jednocześnie.

ProfilDla kogo
GeneralDowolna firma lub organizacja: operator, miejsca i godziny otwarcia, kontakty, języki, co oferuje i za ile, płatność, rezerwacja, czasy odpowiedzi i dostawy, anulowanie, gwarancja, dostępność, licencje, dyspozycyjność. 26 właściwości.
Wynajem pojazdów, Handel detalicznyTo, co jest specyficzne dla branży: kaucja, limit przebiegu, wysyłka, zwroty.
WłasnyWszystko inne. Profil to plik JSON w Państwa domenie; nikogo Państwo nie pytają i niczego nie rejestrują.

Własny profil opisuje Państwa właściwości tak samo jak nasze: etykieta, opis, typ wartości, jednostki, dozwolone kody i warunki. Najmniejsza postać:

{
  "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. Proszę udostępnić plik przez HTTPS pod adresem podanym w id i dodać ten adres do profiles w Państwa źródle.
  2. Proszę zapisać właściwość twierdzenia jako namespace + nazwa, czyli https://dental.example/so4ag-profile#emergencySlot.
  3. Proszę sprawdzić profil i źródło:
    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

Czytnik, który nie zna Państwa profilu, nadal używa twierdzenia, gdy zadanie podaje jego warunki; gdy zadanie ich nie podaje, twierdzenie nie jest używane. Zasady bezpieczeństwa formatu obowiązują więc tak samo dla każdego profilu. Pełny przykład gabinetu stomatologicznego z profilem General i własnym profilem znajduje się w repozytorium: general-dental.json. Schemat profilu: profile.schema.json.

Wolą Państwo nie pisać pliku ręcznie? Usługa SOQVER przygotowuje propozycję na podstawie Państwa witryny; Państwo potwierdzają fakty i publikują źródło u nas albo pobierają je na własną domenę: przygotuj źródło.

5. Odczytuj opublikowane źródła przez API

Interfejs jest tylko do odczytu i nie wymaga konta ani klucza.

curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"

Pierwszy adres zwraca listę źródeł, które firma opublikowała lub potwierdziła. Drugi ocenia twierdzenia jednego źródła pod kątem Państwa zadania i zwraca usable oraz reasons dla każdego z nich. Każde źródło jest też stroną dla ludzi (/s/<slug>/), plikiem /s/<slug>/so4ag.json i postacią JSON-LD /s/<slug>/facts.jsonld.

6. Podłącz agenta przez MCP

Serwer MCP jest tylko do odczytu, nie wymaga konta i korzysta z transportu Streamable HTTP. W oficjalnym MCP Registry jest wymieniony jako com.soqver/so4ag.

https://soqver.com/mcp
NarzędzieDziałanie
list_sourcesWypisuje opublikowane źródła.
get_sourceZwraca całe źródło jednej firmy.
get_claimsOcenia twierdzenia źródła dla danej właściwości i podanych warunków.
check_claimInformuje, czy dane twierdzenie można teraz wykorzystać, oraz dlaczego nie.

W kliencie obsługującym zdalne serwery MCP proszę wpisać powyższy adres. Odpowiedź serwera można też sprawdzić z wiersza poleceń:

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. Napisz własny czytnik

Zestaw zgodności to zwykły JSON i nie wymaga żadnego naszego kodu. Zawiera dwa poprawne źródła w trzech postaciach, oczekiwane skróty twierdzeń, 45 przypadków oceny, 31 przypadków walidacji, 10 przypadków całego źródła i 25 wektorów postaci kanonicznej (RFC 8785).

python readers/python/so4ag_reader.py conformance spec/conformance/0.1

To, kiedy czytnik lub walidator przechodzi zestaw, opisano w opisie zestawu zgodności. Czytnik w języku Python napisano niezależnie od kodu referencyjnego i przechodzi ten sam zestaw; mogą go Państwo wykorzystać jako wzorzec.

Gdzie znaleźć projekt

MiejsceDo czego służy
GitHub: soqvercom/so4agKod, specyfikacja, zestaw testów zgodności i wydania. Tutaj rozwijany jest format.
GitHub DiscussionsMiejsce dla społeczności: pytania, propozycje i doświadczenia z formatem. Odpowiadamy tutaj.
GitHub IssuesBłędy w specyfikacji i w kodzie, przypadki, których format nie potrafi wyrazić.
PyPI: so4agPakiet Python: pip install so4ag
WydaniaPakiet JavaScript i pliki każdej wersji: npm install github:soqvercom/so4ag
Zenodo (DOI)Trwały odnośnik do wydań służący do cytowania w publikacjach i dokumentacji.
MCP RegistryWpis naszego serwera MCP: com.soqver/so4ag
Discord: SOQVER · SO4AGSzybkie pytania i rozmowa z innymi, którzy wypróbowują format.
DEV: @soqvercomArtykuły techniczne i teksty instruktażowe o formacie.
daily.dev: @soqverLinki do nowych artykułów dla programistów.
X · YouTubeAktualności o formacie i krótkie demonstracje.

Uwagi i błędy

Znaleźli Państwo fakt, którego format nie potrafi wyrazić, albo dwa czytniki, które odpowiadają różnie? Prosimy opisać to jako zgłoszenie na GitHub. Lukę w zabezpieczeniach prosimy zgłaszać e-mailem na adres [email protected].