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
最后一条命令用一致性测试套件运行参考代码的测试。全部测试均应通过。
这些软件包可分别通过一条命令安装到您自己的项目中:
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 开头。来源无效时,随后列出错误及其在文件中的位置。无需安装任何软件,浏览器中的验证器即可完成同样的操作。
来源有效仅证明结构正确,并不表示事实为真。
任务指明所询问的属性以及适用条件(范围)。读取方返回每一条匹配的声明,并说明其是否可用;若不可用,则给出原因。
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 | 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 | 该来源使用读取方不认识的格式版本,不会按另一版本的规则进行读取。 |
原因与规则的完整列表见规范。
来源是一个 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),并在到期前确认或更改该声明。此后,读取方将停止使用它。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>"
第一个地址返回企业已发布或已确认的来源列表。第二个地址针对您的任务评估某一来源中的声明,并为每项声明返回 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 读取器独立于参考代码编写,并通过同一套件;您可以将其作为范例。
| 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. |
发现格式无法表达的事实,或两个读取器给出不同的答案?请将其写为 GitHub 上的 issue。请通过电子邮件将漏洞报告至 [email protected]。