SO4AGは、事業者の事実のためのオープンなフォーマットです。各事実は、意味、適用範囲、出自、有効性を持ちます。読み取り側が答える問いは一つです。この事実を、このタスクに、この時点で使用してよいか。使用できない場合、その理由は何か。
形式は無料で、アカウントは不要です。コードは Apache-2.0、仕様の本文は CC BY 4.0 でライセンスされています。
GitHub上のリポジトリ · 仕様 · JSON Schema · 適合性スイート · JSON-LD · ブラウザー上のバリデーター · 動作するもの
Contents: 1. Get the code · 2. Validate a source · 3. Ask about a fact · 4. Publish your own source · 5. API · 6. MCP · 7. Your own reader · Any industry · Where to find the project
Git と Node.js 20 以降が必要です。Python リーダーに必要なのは標準ライブラリのみです(Python 3.10 以降)。
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
最後のコマンドは、参照コードのテストを適合性スイートに対して実行します。すべてが合格するはずです。
ご自身のプロジェクトへは、各パッケージをそれぞれ1つのコマンドでインストールします。
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形式、およびJSON-LDを含むHTMLページを解釈します。
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では第3引数{ 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 | The source carries an attestation with the name of an issuer you trust, but you have not authenticated it with the issuer. A name written in the source is not a proof. |
conflicting_claims | Two current claims state different values for the same thing. The reader uses neither and never picks a winner silently. |
invalid_source | The source breaks the structure of the format (for example a claim without evidence or an unreadable date). Nothing of it is used. |
unsupported_version | そのソースは、読み取り側が知らないフォーマットのバージョンです。別のバージョンの規則では読み取られません。 |
理由と規則の完全な一覧は、仕様にあります。
ソースは1つのJSONファイルです。実用上最小の形は、公開者と1件の主張を持ちます。
{
"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)を設け、それが過ぎる前に主張を確認または変更してください。その時点を過ぎると、読み取り側はそれを使用しなくなります。The format is not tied to an industry. Properties (what a fact means, its type and unit, and which conditions limit it) are set by a profile, and one source may use several profiles together.
| プロファイル | For whom |
|---|---|
| General | Any business or organisation: operator, places and opening hours, contacts, languages, what it offers and for how much, payment, booking, response and delivery times, cancellation, guarantee, accessibility, licences, availability. 26 properties. |
| Vehicle rental, Retail | What is specific to the industry: deposit, mileage limit, shipping, returns. |
| Your own | Anything else. A profile is a JSON file on your domain; you ask nobody and register nothing. |
Your own profile describes your properties the same way ours do: label, description, value type, units, allowed codes and conditions. The smallest form:
{
"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 and add that address to profiles in your source.namespace + name, that is 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.jsonA reader that does not know your profile still uses the claim when the task states its conditions; when the task does not, the claim is not used. The safety rules of the format therefore hold for every profile alike. A complete example of a dental practice with the General profile and its own profile is in the repository: general-dental.json. Schema of a profile: 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>"
最初のアドレスは、企業が公開または確認したソースの一覧を返します。2番目は、1つのソースの主張をお客様のタスクに照らして評価し、それぞれについて 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 | 1つの事業者のソース全体を返します。 |
get_claims | 指定したプロパティと条件に対して、ソースの主張を評価します。 |
check_claim | 1つの主張を現時点で使用できるかと、使用できない理由を示します。 |
リモート 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 であり、当社のコードは不要です。有効なソース2件を3つの形式で収め、クレームの期待ダイジェスト、評価ケース 45 件、検証ケース 31 件、ソース全体のケース 10 件、正規形のベクトル 25 件(RFC 8785)を含みます。
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
リーダーまたはバリデーターがスイートに合格する条件は、適合スイートの説明に記載しています。Python リーダーは参照コードとは独立して作成され、同じスイートに合格します。実装の手本としてご利用いただけます。
| Place | What it is for |
|---|---|
| GitHub: soqvercom/so4ag | Code, specification, conformance suite and releases. This is where the format is developed. |
| GitHub Discussions | The place for the community: questions, proposals and experience with the format. We answer here. |
| GitHub Issues | Errors in the specification and the code, cases the format cannot express. |
| PyPI: so4ag | The Python package: pip install so4ag |
| Releases | The JavaScript package and the files of every version: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | A permanent link to the releases for citing in papers and documentation. |
| MCP Registry | The entry of our MCP server: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Quick questions and a chat with others who try the format. |
| DEV: @soqvercom | Technical articles and how-to texts about the format. |
| daily.dev: @soqver | Links to new articles for developers. |
| X · YouTube | News about the format and short demos. |
形式では表現できない事実や、回答が異なる2つのリーダーが見つかりましたか。GitHub の issue としてご記入ください。脆弱性はメールで [email protected] までご報告ください。