SOQVER Підготувати джерело
Українська

Посібник для розробників

SO4AG — відкритий формат бізнес-фактів: кожен факт містить своє значення, сферу застосування, походження та чинність. Читач відповідає на одне запитання: чи можна використати цей факт для цього завдання в цей час, а якщо ні — чому.

Формат безкоштовний і не потребує облікового запису. Код ліцензовано за Apache-2.0, текст специфікації — за CC BY 4.0.

Усе в одному місці

Репозиторій на GitHub · специфікація · JSON Schema · набір відповідності · JSON-LD · валідатор у браузері · що працює

Зміст: 1. Отримати код · 2. Перевірити джерело · 3. Запитати про факт · 4. Опублікувати власне джерело · 5. API · 6. MCP · 7. Власний читач · Будь-яка галузь · Де знайти проєкт

1. Отримати код

Потрібні 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

2. Перевірити джерело

Валідатор читає файл або адресу. Він розуміє 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. Для невалідного джерела далі йде список помилок із зазначенням місця у файлі. Без жодного встановлення те саме працює у валідаторі в браузері.

Валідне джерело підтверджує лише правильну структуру. Воно не стверджує, що факт правдивий.

3. Запитати, чи можна використати факт

Завдання зазначає, про яку властивість ви запитуєте і за яких умов (сфера застосування). Читач повертає кожне відповідне твердження з відповіддю, чи воно придатне, і з причинами, якщо ні.

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

Спробуйте те саме без умови філії або в інший час (--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Джерело належить до версії формату, яку читач не знає. Його не читають за правилами іншої версії.

Повний перелік причин і правил міститься у специфікації.

4. Опублікувати власне джерело

Джерело — це один файл 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"
    }
  ]
}
  1. Збережіть файл як so4ag.json і перевірте його валідатором (крок 2).
  2. Віддавайте його через HTTPS на своєму домені за адресою /so4ag.json з типом application/json.
  3. Додайте посилання на джерело на сторінки для людей:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Щоб ті самі факти були всередині сторінки, перетворіть джерело на JSON-LD і вмістіть результат у тег <script type="application/ld+json">. Перетворення відбувається без втрат.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Задайте кожному твердженню кінець чинності (valid_until) і підтвердьте або змініть твердження, перш ніж він мине. Після цього часу читачі припиняють його використовувати.

Будь-яка галузь: профіль General і ваш власний профіль

Формат не прив’язаний до галузі. Властивості (що означає факт, його тип і одиниця, а також які умови його обмежують) задає профіль, і одне джерело може використовувати кілька профілів разом.

ПрофільДля кого
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."
    }
  }
}
  1. Віддавайте файл через HTTPS за адресою, указаною в id, і додайте цю адресу до profiles у своєму джерелі.
  2. Записуйте властивість твердження як namespace + назва, тобто https://dental.example/so4ag-profile#emergencySlot.
  3. Перевірте профіль і джерело:
    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 готує пропозицію з вашого сайту, ви підтверджуєте факти й публікуєте джерело в нас або завантажуєте його для власного домену: підготувати джерело.

5. Читати опубліковані джерела через API

Інтерфейс доступний лише для читання і не потребує облікового запису та ключа.

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.

6. Підключити агента через MCP

Сервер 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"}'

7. Написати власного читача

Набір відповідності — це звичайний 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].