SOQVER Chuẩn bị nguồn
Tiếng Việt

Hướng dẫn cho nhà phát triển

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.

Tất cả ở một nơi

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

1. Lấy mã nguồn

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

2. Kiểm tra một nguồn

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.

3. Hỏi xem một dữ kiện có được dùng hay khô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.

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

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_validKhẳ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_applicableBê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.
disputedKhẳng định đang bị tranh chấp.
no_trust_policyTá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_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_versionNguồ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ả.

4. Công bố nguồn của quý vị

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"
    }
  ]
}
  1. Lưu tệp dưới tên so4ag.json và kiểm tra bằng trình kiểm tra (bước 2).
  2. Phục vụ tệp qua HTTPS trên tên miền của quý vị tại /so4ag.json với kiểu application/json.
  3. Thêm liên kết tới nguồn vào các trang dành cho người đọc:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Để có cùng các dữ kiện bên trong trang, hãy chuyển nguồn sang JSON-LD và đặt kết quả vào thẻ <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.jsonld
  5. Hãy đặt thời điểm hết hiệu lực (valid_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.

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.

Hồ sơ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.

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.

5. Đọc các nguồn đã công bố qua API

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.

6. Kết nối một agent qua MCP

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_sourcesLiệt kê các nguồn đã công bố.
get_sourceTrả 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_claimCho 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"}'

7. Viết trình đọc của riêng quý vị

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.

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.

Phản hồi và lỗi

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].