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

最后一条命令用一致性测试套件运行参考代码的测试。全部测试均应通过。

这些软件包可分别通过一条命令安装到您自己的项目中:

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. 询问某项事实是否可以使用

任务指明所询问的属性以及适用条件(范围)。读取方返回每一条匹配的声明,并说明其是否可用;若不可用,则给出原因。

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_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. 发布您自己的来源

来源是一个 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),并在到期前确认或更改该声明。此后,读取方将停止使用它。

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>"

第一个地址返回企业已发布或已确认的来源列表。第二个地址针对您的任务评估某一来源中的声明,并为每项声明返回 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 读取器独立于参考代码编写,并通过同一套件;您可以将其作为范例。

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.

反馈与错误

发现格式无法表达的事实,或两个读取器给出不同的答案?请将其写为 GitHub 上的 issue。请通过电子邮件将漏洞报告至 [email protected]。