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 และหน้า HTML ที่มี JSON-LD อยู่ภายใน

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 โปรดรายงานช่องโหว่ทางอีเมลถึง [email protected]