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 และหน้า 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 หากแหล่งข้อมูลไม่ถูกต้อง จะตามด้วยรายการข้อผิดพลาดพร้อมตำแหน่งในไฟล์ โดยไม่ต้องติดตั้งสิ่งใด การทำงานเดียวกันใช้ได้ใน ตัวตรวจสอบในเบราว์เซอร์
แหล่งข้อมูลที่ถูกต้องพิสูจน์เพียงว่าโครงสร้างถูกต้อง ไม่ได้บ่งชี้ว่าข้อเท็จจริงเป็นจริง
งานระบุคุณสมบัติที่สอบถามและเงื่อนไข (ขอบเขต) ที่ใช้ ตัวอ่านส่งคืนข้อกล่าวอ้างที่ตรงกันทุกรายการ พร้อมคำตอบว่าใช้ได้หรือไม่ และเหตุผลเมื่อใช้ไม่ได้
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 โปรดรายงานช่องโหว่ทางอีเมลถึง [email protected]