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
Валидатор читает файл или адрес. Он понимает 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. Для недействительного источника далее следует список ошибок с указанием места в файле. Без установки чего-либо то же самое работает в валидаторе в браузере.
Действительный источник подтверждает только правильность структуры. Он не утверждает, что факт истинен.
Задача указывает, о каком свойстве вы спрашиваете и при каких условиях (scope). Читатель возвращает каждое подходящее утверждение с ответом, можно ли его использовать, и с причинами, если нельзя.
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].