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. Проверьте источник

Валидатор читает файл или адрес. Он понимает JSON формата SO4AG, форму 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. Узнайте, можно ли использовать факт

Задача указывает, о каком свойстве вы спрашиваете и при каких условиях (scope). Читатель возвращает каждое подходящее утверждение с ответом, можно ли его использовать, и с причинами, если нельзя.

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