SOQVER ソースを準備
日本語

開発者向けガイド

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

1. コードを入手する

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

2. ソースを検証する

バリデーターは、ファイルまたはアドレスを読み取ります。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 で始まります。無効なソースの場合は、ファイル内の位置を添えたエラーの一覧が続きます。何もインストールしなくても、ブラウザー上のバリデーターで同じことができます。

有効なソースが証明するのは、構造が正しいことだけです。事実が真実であることまでは示しません。

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では第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_authenticatedThe 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_claimsTwo current claims state different values for the same thing. The reader uses neither and never picks a winner silently.
invalid_sourceThe source breaks the structure of the format (for example a claim without evidence or an unreadable date). Nothing of it is used.
unsupported_versionそのソースは、読み取り側が知らないフォーマットのバージョンです。別のバージョンの規則では読み取られません。

理由と規則の完全な一覧は、仕様にあります。

4. 独自のソースを公開する

ソースは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"
    }
  ]
}
  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)を設け、それが過ぎる前に主張を確認または変更してください。その時点を過ぎると、読み取り側はそれを使用しなくなります。

Any industry: the General profile and your own profile

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
GeneralAny 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, RetailWhat is specific to the industry: deposit, mileage limit, shipping, returns.
Your ownAnything 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."
    }
  }
}
  1. Serve the file over HTTPS at the address given in id and add that address to profiles in your source.
  2. Write the property of a claim as namespace + name, that is https://dental.example/so4ag-profile#emergencySlot.
  3. Check the profile and the source:
    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

A 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のサービスがお客様のウェブサイトから提案を作成します。事実をご確認のうえ、当社でソースを公開するか、ご自身のドメイン用にダウンロードできます。ソースを準備する

5. API で公開ソースを読み取る

インターフェースは読み取り専用で、アカウントもキーも不要です。

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 でもあります。

6. MCP でエージェントを接続する

MCP サーバーは読み取り専用で、アカウントは不要であり、Streamable HTTP トランスポートを使用します。公式の MCP Registry では com.soqver/so4ag として掲載されています。

https://soqver.com/mcp
ツール機能
list_sources公開されたソースを一覧表示します。
get_source1つの事業者のソース全体を返します。
get_claims指定したプロパティと条件に対して、ソースの主張を評価します。
check_claim1つの主張を現時点で使用できるかと、使用できない理由を示します。

リモート 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 であり、当社のコードは不要です。有効なソース2件を3つの形式で収め、クレームの期待ダイジェスト、評価ケース 45 件、検証ケース 31 件、ソース全体のケース 10 件、正規形のベクトル 25 件(RFC 8785)を含みます。

python readers/python/so4ag_reader.py conformance spec/conformance/0.1

リーダーまたはバリデーターがスイートに合格する条件は、適合スイートの説明に記載しています。Python リーダーは参照コードとは独立して作成され、同じスイートに合格します。実装の手本としてご利用いただけます。

Where to find the project

PlaceWhat it is for
GitHub: soqvercom/so4agCode, specification, conformance suite and releases. This is where the format is developed.
GitHub DiscussionsThe place for the community: questions, proposals and experience with the format. We answer here.
GitHub IssuesErrors in the specification and the code, cases the format cannot express.
PyPI: so4agThe Python package: pip install so4ag
ReleasesThe 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 RegistryThe entry of our MCP server: com.soqver/so4ag
Discord: SOQVER · SO4AGQuick questions and a chat with others who try the format.
DEV: @soqvercomTechnical articles and how-to texts about the format.
daily.dev: @soqverLinks to new articles for developers.
X · YouTubeNews about the format and short demos.

フィードバックと不具合

形式では表現できない事実や、回答が異なる2つのリーダーが見つかりましたか。GitHub の issue としてご記入ください。脆弱性はメールで [email protected] までご報告ください。