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.
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
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
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.
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.
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
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ód | Znaczenie |
|---|---|
expired, not_yet_valid | Twierdzenie 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_applicable | Wydawca wyraźnie stwierdza, że wartość nie jest znana albo nie ma zastosowania. Nieznane nie oznacza zera. |
disputed | Twierdzenie jest sporne. |
no_trust_policy | Zadanie 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_claims | Dwa 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.
Ź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"
}
]
}
so4ag.json i sprawdzić go walidatorem (krok 2)./so4ag.json z typem application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. Konwersja jest bezstratna. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) oraz potwierdzić je lub zmienić, zanim ten moment minie. Po tym czasie czytniki przestają z niego korzystać.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.
| Profil | Dla kogo |
|---|---|
| General | Dowolna 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 detaliczny | To, co jest specyficzne dla branży: kaucja, limit przebiegu, wysyłka, zwroty. |
| Własny | Wszystko 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."
}
}
}
id i dodać ten adres do profiles w Państwa źródle.namespace + nazwa, czyli 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.jsonCzytnik, 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.
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.
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ędzie | Działanie |
|---|---|
list_sources | Wypisuje opublikowane źródła. |
get_source | Zwraca całe źródło jednej firmy. |
get_claims | Ocenia twierdzenia źródła dla danej właściwości i podanych warunków. |
check_claim | Informuje, 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"}'
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.
| Miejsce | Do czego służy |
|---|---|
| GitHub: soqvercom/so4ag | Kod, specyfikacja, zestaw testów zgodności i wydania. Tutaj rozwijany jest format. |
| GitHub Discussions | Miejsce dla społeczności: pytania, propozycje i doświadczenia z formatem. Odpowiadamy tutaj. |
| GitHub Issues | Błędy w specyfikacji i w kodzie, przypadki, których format nie potrafi wyrazić. |
| PyPI: so4ag | Pakiet Python: pip install so4ag |
| Wydania | Pakiet 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 Registry | Wpis naszego serwera MCP: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Szybkie pytania i rozmowa z innymi, którzy wypróbowują format. |
| DEV: @soqvercom | Artykuły techniczne i teksty instruktażowe o formacie. |
| daily.dev: @soqver | Linki do nowych artykułów dla programistów. |
| X · YouTube | Aktualności o formacie i krótkie demonstracje. |
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].