SO4AG là định dạng mở cho dữ kiện doanh nghiệp: mỗi dữ kiện mang ý nghĩa, phạm vi, nguồn gốc và hiệu lực. Bộ đọc trả lời một câu hỏi: dữ kiện này có được dùng cho tác vụ này vào thời điểm này hay không, và nếu không thì vì sao.
Định dạng miễn phí và không cần tài khoản. Mã nguồn được cấp phép theo Apache-2.0, văn bản đặc tả theo CC BY 4.0.
Kho lưu trữ trên GitHub · đặc tả · JSON Schema · bộ kiểm thử tuân thủ · JSON-LD · trình kiểm tra trên trình duyệt · những gì hoạt động
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
Quý vị cần Git và Node.js 20 trở lên. Trình đọc Python chỉ cần thư viện chuẩn (Python 3.10 trở lên).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
Lệnh cuối chạy các bài kiểm thử của mã tham chiếu với bộ kiểm thử tuân thủ. Tất cả đều phải đạt.
Các gói được cài vào dự án của quý vị, mỗi gói bằng một lệnh:
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
Trình kiểm tra đọc một tệp hoặc một địa chỉ. Trình kiểm tra hiểu JSON SO4AG, dạng JSON-LD và trang HTML có JSON-LD bên trong.
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
Câu trả lời bắt đầu bằng VALID hoặc INVALID. Với nguồn không hợp lệ, tiếp theo là danh sách lỗi kèm vị trí trong tệp. Không cần cài đặt gì, cách này cũng hoạt động trong trình kiểm tra trên trình duyệt.
Nguồn hợp lệ chỉ chứng minh cấu trúc đúng. Nguồn không nói dữ kiện là đúng.
Một tác vụ nêu thuộc tính quý vị hỏi và các điều kiện (phạm vi). Bộ đọc trả về mọi khẳng định khớp, kèm câu trả lời liệu khẳng định có dùng được hay không, và lý do khi không dùng được.
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
Hãy thử tương tự khi bỏ điều kiện chi nhánh hoặc vào thời điểm khác (--now 2027-06-01T12:00:00Z, trong JavaScript đối số thứ ba là { now: new Date(…) }). Khẳng định không còn dùng được và bộ đọc nêu lý do.
| Lý do | Ý nghĩa |
|---|---|
expired, not_yet_valid | Khẳng định không có hiệu lực tại thời điểm câu hỏi. |
scope_mismatch:<key> | Khẳng định có hiệu lực với một giá trị khác của điều kiện, ví dụ một chi nhánh khác. |
scope_not_in_task:<key> | Khẳng định bị giới hạn bởi một điều kiện mà tác vụ không nêu. Không có điều kiện đó, không ai xác định được khẳng định có áp dụng hay không. |
unknown, not_applicable | Bên công bố nêu rõ giá trị không xác định hoặc không áp dụng. Không xác định không phải là số không. |
disputed | Khẳng định đang bị tranh chấp. |
no_trust_policy | Tác vụ yêu cầu một khẳng định đã được rà soát nhưng không nêu tin cậy ai. Việc tin ai là quyết định của người đọc khẳng định. |
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 | Nguồn thuộc một phiên bản định dạng mà bộ đọc không biết. Nguồn không được đọc theo quy tắc của phiên bản khác. |
Danh sách đầy đủ các lý do và quy tắc nằm trong đặc tả.
Một nguồn là một tệp JSON. Dạng hữu ích nhỏ nhất gồm một bên công bố và một khẳng định:
{
"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 và kiểm tra bằng trình kiểm tra (bước 2)./so4ag.json với kiểu application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. Việc chuyển đổi không làm mất dữ liệu. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) cho mọi khẳng định và xác nhận hoặc thay đổi khẳng định trước khi thời điểm đó qua. Sau thời điểm đó, bộ đọc ngừng sử dụng khẳng định.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.
| Hồ sơ | 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.
Không muốn viết tệp bằng tay? Dịch vụ SOQVER lập một đề xuất từ trang web của quý vị; quý vị xác nhận các dữ kiện và công bố nguồn cùng chúng tôi hoặc tải về cho tên miền của mình: chuẩn bị nguồn.
Giao diện chỉ đọc, không cần tài khoản và không cần khóa.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
Địa chỉ thứ nhất trả về danh sách các nguồn mà một công ty đã công bố hoặc xác nhận. Địa chỉ thứ hai đánh giá các khẳng định của một nguồn theo tác vụ của quý vị và trả về usable và reasons cho từng khẳng định. Mỗi nguồn cũng là một trang dành cho người dùng (/s/<slug>/), một tệp /s/<slug>/so4ag.json và một dạng JSON-LD /s/<slug>/facts.jsonld.
Máy chủ MCP chỉ đọc, không cần tài khoản và dùng phương thức truyền Streamable HTTP. Trong MCP Registry chính thức, máy chủ được liệt kê là com.soqver/so4ag.
https://soqver.com/mcp
| Công cụ | Chức năng |
|---|---|
list_sources | Liệt kê các nguồn đã công bố. |
get_source | Trả về toàn bộ nguồn của một doanh nghiệp. |
get_claims | Đánh giá các khẳng định của một nguồn theo thuộc tính và điều kiện đã cho. |
check_claim | Cho biết một khẳng định hiện có được dùng hay không, và vì sao không. |
Trong ứng dụng khách hỗ trợ máy chủ MCP từ xa, hãy nhập địa chỉ ở trên. Quý vị cũng có thể kiểm tra phản hồi của máy chủ từ dòng lệnh:
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"}'
Bộ kiểm thử tuân thủ là JSON thuần và không cần mã của chúng tôi. Bộ này chứa hai nguồn hợp lệ ở ba dạng, các giá trị băm kỳ vọng của các khẳng định, 45 trường hợp đánh giá, 31 trường hợp xác thực, 10 trường hợp toàn nguồn và 25 vectơ của dạng chính tắc (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Điều kiện để trình đọc hoặc trình kiểm tra đạt bộ kiểm thử được mô tả trong mô tả bộ kiểm thử tuân thủ. Trình đọc Python được viết độc lập với mã tham chiếu và đạt cùng bộ kiểm thử; quý vị có thể dùng nó làm mẫu.
| 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. |
Quý vị phát hiện một dữ kiện mà định dạng không thể biểu đạt, hoặc hai trình đọc đưa ra câu trả lời khác nhau? Hãy ghi lại dưới dạng issue trên GitHub. Vui lòng báo cáo lỗ hổng qua e-mail tới [email protected].