SO4AG — відкритий формат бізнес-фактів: кожен факт містить своє значення, сферу застосування, походження та чинність. Читач відповідає на одне запитання: чи можна використати цей факт для цього завдання в цей час, а якщо ні — чому.
Формат безкоштовний і не потребує облікового запису. Код ліцензовано за Apache-2.0, текст специфікації — за CC BY 4.0.
Репозиторій на GitHub · специфікація · JSON Schema · набір відповідності · JSON-LD · валідатор у браузері · що працює
Зміст: 1. Отримати код · 2. Перевірити джерело · 3. Запитати про факт · 4. Опублікувати власне джерело · 5. API · 6. MCP · 7. Власний читач · Будь-яка галузь · Де знайти проєкт
Потрібні Git і Node.js 20 або новіший. Читачу Python достатньо стандартної бібліотеки (Python 3.10 або новіший).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
Остання команда запускає тести еталонного коду на наборі відповідності. Усі вони мають пройти.
У ваш власний проєкт пакети встановлюються однією командою кожен:
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
Валідатор читає файл або адресу. Він розуміє SO4AG JSON, форму JSON-LD і HTML-сторінку з 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
Відповідь починається з VALID або INVALID. Для невалідного джерела далі йде список помилок із зазначенням місця у файлі. Без жодного встановлення те саме працює у валідаторі в браузері.
Валідне джерело підтверджує лише правильну структуру. Воно не стверджує, що факт правдивий.
Завдання зазначає, про яку властивість ви запитуєте і за яких умов (сфера застосування). Читач повертає кожне відповідне твердження з відповіддю, чи воно придатне, і з причинами, якщо ні.
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
Спробуйте те саме без умови філії або в інший час (--now 2027-06-01T12:00:00Z, у JavaScript третій аргумент { now: new Date(…) }). Твердження перестає бути придатним, і читач пояснює чому.
| Причина | Що це означає |
|---|---|
expired, not_yet_valid | Твердження не чинне на момент запитання. |
scope_mismatch:<key> | Твердження чинне для іншого значення умови, наприклад для іншої філії. |
scope_not_in_task:<key> | Твердження обмежене умовою, яку завдання не зазначає. Без неї ніхто не може сказати, чи твердження застосовується. |
unknown, not_applicable | Видавець прямо зазначає, що значення невідоме або не застосовується. Невідоме — це не нуль. |
disputed | Твердження оскаржено. |
no_trust_policy | Завдання запитує перевірене твердження, але не вказує, кому довіряє. Кому довіряти — рішення того, хто читає твердження. |
attestation_not_authenticated | Джерело містить атестацію з іменем видавця, якому ви довіряєте, але ви не автентифікували її у видавця. Ім'я, записане в джерелі, не є доказом. |
conflicting_claims | Два чинні твердження наводять різні значення для одного й того самого. Читач не використовує жодного з них і ніколи мовчки не обирає переможця. |
invalid_source | Джерело порушує структуру формату (наприклад, твердження без доказу або нечитабельна дата). Нічого з нього не використовується. |
unsupported_version | Джерело належить до версії формату, яку читач не знає. Його не читають за правилами іншої версії. |
Повний перелік причин і правил міститься у специфікації.
Джерело — це один файл JSON. Найменша корисна форма містить видавця й одне твердження:
{
"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 і перевірте його валідатором (крок 2)./so4ag.json з типом application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. Перетворення відбувається без втрат. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) і підтвердьте або змініть твердження, перш ніж він мине. Після цього часу читачі припиняють його використовувати.Формат не прив’язаний до галузі. Властивості (що означає факт, його тип і одиниця, а також які умови його обмежують) задає профіль, і одне джерело може використовувати кілька профілів разом.
| Профіль | Для кого |
|---|---|
| General | Будь-який бізнес або організація: оператор, місця та години роботи, контакти, мови, що пропонує і за скільки, оплата, бронювання, час відповіді та доставки, скасування, гарантія, доступність, ліцензії, наявність. 26 властивостей. |
| Оренда транспорту, Роздрібна торгівля | Що є специфічним для галузі: застава, ліміт пробігу, доставка, повернення. |
| Власний | Усе інше. Профіль — це файл JSON на вашому домені; ви ні в кого не запитуєте і нічого не реєструєте. |
Ваш власний профіль описує ваші властивості так само, як наші: назва, опис, тип значення, одиниці, дозволені коди й умови. Найменша форма:
{
"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, і додайте цю адресу до profiles у своєму джерелі.namespace + назва, тобто 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.jsonЧитач, який не знає вашого профілю, все одно використовує твердження, якщо завдання зазначає його умови; якщо завдання їх не зазначає, твердження не використовується. Отже, правила безпеки формату діють для кожного профілю однаково. Повний приклад стоматологічної практики з профілем General і власним профілем є в репозиторії: general-dental.json. Схема профілю: profile.schema.json.
Не бажаєте писати файл вручну? Сервіс SOQVER готує пропозицію з вашого сайту, ви підтверджуєте факти й публікуєте джерело в нас або завантажуєте його для власного домену: підготувати джерело.
Інтерфейс доступний лише для читання і не потребує облікового запису та ключа.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
Перша адреса повертає список джерел, які компанія опублікувала або підтвердила. Друга оцінює твердження одного джерела для вашого завдання і повертає для кожного usable та reasons. Кожне джерело є також сторінкою для людей (/s/<slug>/), файлом /s/<slug>/so4ag.json і формою JSON-LD /s/<slug>/facts.jsonld.
Сервер MCP доступний лише для читання, не потребує облікового запису і використовує транспорт Streamable HTTP. В офіційному MCP Registry його зазначено як com.soqver/so4ag.
https://soqver.com/mcp
| Інструмент | Що робить |
|---|---|
list_sources | Перелічує опубліковані джерела. |
get_source | Повертає повне джерело одного бізнесу. |
get_claims | Оцінює твердження джерела для заданої властивості та умов. |
check_claim | Повідомляє, чи можна використати одне твердження зараз, і чому ні. |
У клієнті, який підтримує віддалені сервери MCP, введіть адресу вище. Відповідь сервера можна перевірити і з командного рядка:
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"}'
Набір відповідності — це звичайний JSON, і він не потребує жодного нашого коду. Він містить два дійсні джерела у трьох формах, очікувані дайджести тверджень, 45 випадків оцінювання, 31 випадок валідації, 10 випадків цілого джерела та 25 векторів канонічної форми (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Умови, за яких читач або валідатор проходить набір, описано в описі набору відповідності. Читач Python написаний незалежно від еталонного коду і проходить той самий набір; його можна взяти за зразок.
| Місце | Для чого це |
|---|---|
| GitHub: soqvercom/so4ag | Код, специфікація, набір тестів відповідності та релізи. Саме тут розробляється формат. |
| GitHub Discussions | Місце для спільноти: запитання, пропозиції та досвід роботи з форматом. Відповідаємо тут. |
| GitHub Issues | Помилки в специфікації та коді, випадки, які формат не може виразити. |
| PyPI: so4ag | Пакет Python: pip install so4ag |
| Релізи | Пакет JavaScript і файли кожної версії: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Постійне посилання на релізи для цитування в статтях і документації. |
| MCP Registry | Запис нашого сервера MCP: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Короткі запитання та спілкування з тими, хто випробовує формат. |
| DEV: @soqvercom | Технічні статті та практичні інструкції про формат. |
| daily.dev: @soqver | Посилання на нові статті для розробників. |
| X · YouTube | Новини про формат і короткі демонстрації. |
Знайшли факт, який формат не може виразити, або двох читачів, які відповідають по-різному? Опишіть це як issue на GitHub. Про вразливість повідомте електронною поштою на адресу [email protected].