SO4AG adalah format terbuka untuk fakta bisnis: setiap fakta memuat makna, cakupan, asal, dan masa berlakunya. Pembaca menjawab satu pertanyaan: apakah fakta ini boleh digunakan untuk tugas ini pada saat ini, dan jika tidak, mengapa.
Format ini gratis dan tidak memerlukan akun. Kode dilisensikan di bawah Apache-2.0, teks spesifikasi di bawah CC BY 4.0.
Repositori di GitHub · spesifikasi · JSON Schema · rangkaian kesesuaian · JSON-LD · validator di peramban · yang berfungsi
Daftar isi: 1. Ambil kode · 2. Validasi sumber · 3. Tanyakan suatu fakta · 4. Terbitkan sumber Anda sendiri · 5. API · 6. MCP · 7. Pembaca Anda sendiri · Industri apa pun · Tempat menemukan proyek
Anda memerlukan Git dan Node.js 20 atau yang lebih baru. Pembaca Python hanya memerlukan pustaka standar (Python 3.10 atau yang lebih baru).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
Perintah terakhir menjalankan pengujian kode referensi terhadap rangkaian kesesuaian. Semuanya seharusnya lulus.
Ke dalam proyek Anda sendiri, paket-paket terinstal masing-masing dengan satu perintah:
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
Validator membaca berkas atau alamat. Validator memahami JSON SO4AG, bentuk JSON-LD, dan halaman HTML yang memuat JSON-LD di dalamnya.
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
Jawaban dimulai dengan VALID atau INVALID. Untuk sumber yang tidak valid, daftar kesalahan beserta letaknya dalam berkas menyusul. Tanpa memasang apa pun, hal yang sama berfungsi di validator di peramban.
Sumber yang valid hanya membuktikan struktur yang benar. Sumber tersebut tidak menyatakan bahwa faktanya benar.
Tugas menyatakan properti yang Anda tanyakan dan untuk kondisi yang mana (cakupan). Pembaca mengembalikan setiap klaim yang cocok beserta jawaban apakah klaim tersebut dapat digunakan, serta alasannya jika tidak.
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
Coba hal yang sama tanpa kondisi cabang atau pada waktu lain (--now 2027-06-01T12:00:00Z, dalam JavaScript argumen ketiga { now: new Date(…) }). Klaim berhenti dapat digunakan dan pembaca menjelaskan alasannya.
| Alasan | Artinya |
|---|---|
expired, not_yet_valid | Klaim tidak berlaku pada waktu pertanyaan diajukan. |
scope_mismatch:<key> | Klaim berlaku untuk nilai kondisi yang lain, misalnya cabang lain. |
scope_not_in_task:<key> | Klaim dibatasi oleh kondisi yang tidak dinyatakan oleh tugas. Tanpa kondisi itu, tidak seorang pun dapat mengatakan apakah klaim berlaku. |
unknown, not_applicable | Penerbit menyatakan secara eksplisit bahwa nilai tidak diketahui atau tidak berlaku. Tidak diketahui bukan berarti nol. |
disputed | Klaim disengketakan. |
no_trust_policy | Tugas meminta klaim yang telah ditinjau, tetapi tidak menyatakan pihak yang dipercayainya. Pihak yang dipercaya merupakan keputusan pihak yang membaca klaim. |
attestation_not_authenticated | Sumber memuat atestasi dengan nama penerbit yang Anda percayai, tetapi Anda belum mengautentikasinya dengan penerbit tersebut. Nama yang tertulis dalam sumber bukan bukti. |
conflicting_claims | Dua klaim yang berlaku menyatakan nilai yang berbeda untuk hal yang sama. Pembaca tidak menggunakan keduanya dan tidak pernah memilih pemenang secara diam-diam. |
invalid_source | Sumber melanggar struktur format (misalnya klaim tanpa bukti atau tanggal yang tidak terbaca). Tidak ada bagiannya yang digunakan. |
unsupported_version | Sumber menggunakan versi format yang tidak dikenal pembaca. Sumber tidak dibaca menurut aturan versi lain. |
Daftar lengkap alasan dan aturan terdapat dalam spesifikasi.
Sumber adalah satu berkas JSON. Bentuk terkecil yang berguna memiliki penerbit dan satu klaim:
{
"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 dan periksa dengan validator (langkah 2)./so4ag.json dengan tipe application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. Konversi ini tanpa kehilangan data. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) serta konfirmasikan atau ubah klaim sebelum waktu itu terlewati. Setelah waktu tersebut, pembaca berhenti menggunakannya.Format tidak terikat pada industri tertentu. Properti (makna suatu fakta, tipe dan satuannya, serta kondisi yang membatasinya) ditetapkan oleh profil, dan satu sumber dapat memakai beberapa profil sekaligus.
| Profil | Untuk siapa |
|---|---|
| General | Setiap usaha atau organisasi: operator, lokasi dan jam buka, kontak, bahasa, apa yang ditawarkan dan berapa harganya, pembayaran, pemesanan, waktu respons dan pengiriman, pembatalan, jaminan, aksesibilitas, lisensi, ketersediaan. 26 properti. |
| Penyewaan kendaraan, Ritel | Hal yang khusus bagi industri: deposit, batas jarak tempuh, pengiriman, pengembalian. |
| Milik Anda | Hal lainnya. Profil adalah berkas JSON di domain Anda; Anda tidak meminta izin kepada siapa pun dan tidak mendaftarkan apa pun. |
Profil Anda sendiri menjelaskan properti Anda dengan cara yang sama seperti profil kami: label, deskripsi, tipe nilai, satuan, kode yang diizinkan, dan kondisi. Bentuk terkecil:
{
"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 dan tambahkan alamat tersebut ke profiles pada sumber Anda.namespace + nama, yaitu 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.jsonPembaca yang tidak mengenal profil Anda tetap menggunakan klaim bila tugas menyatakan syaratnya; bila tugas tidak menyatakannya, klaim tidak digunakan. Karena itu, aturan keselamatan format berlaku sama untuk setiap profil. Contoh lengkap praktik dokter gigi dengan profil General dan profilnya sendiri ada di repositori: general-dental.json. Skema profil: profile.schema.json.
Tidak ingin menulis berkas secara manual? Layanan SOQVER menyiapkan usulan dari situs web Anda; Anda mengonfirmasi fakta, lalu menerbitkan sumber bersama kami atau mengunduhnya untuk domain Anda sendiri: siapkan sumber.
Antarmuka bersifat hanya-baca dan tidak memerlukan akun maupun kunci.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
Alamat pertama mengembalikan daftar sumber yang diterbitkan atau dikonfirmasi suatu perusahaan. Alamat kedua mengevaluasi klaim dari satu sumber untuk tugas Anda dan mengembalikan usable serta reasons untuk masing-masing. Setiap sumber juga berupa halaman untuk orang (/s/<slug>/), berkas /s/<slug>/so4ag.json, dan bentuk JSON-LD /s/<slug>/facts.jsonld.
Server MCP bersifat hanya-baca, tidak memerlukan akun, dan menggunakan transport Streamable HTTP. Di MCP Registry resmi, server ini tercantum sebagai com.soqver/so4ag.
https://soqver.com/mcp
| Alat | Fungsinya |
|---|---|
list_sources | Menampilkan daftar sumber yang diterbitkan. |
get_source | Mengembalikan seluruh sumber dari satu bisnis. |
get_claims | Mengevaluasi klaim suatu sumber untuk properti dan kondisi yang diberikan. |
check_claim | Menyatakan apakah satu klaim boleh digunakan sekarang, dan mengapa tidak. |
Pada klien yang mendukung server MCP jarak jauh, masukkan alamat di atas. Anda juga dapat memeriksa jawaban server dari baris perintah:
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"}'
Suite kesesuaian berupa JSON biasa dan tidak memerlukan kode kami. Suite ini memuat dua sumber yang valid dalam tiga bentuk, digest klaim yang diharapkan, 45 kasus evaluasi, 31 kasus validasi, 10 kasus sumber utuh, dan 25 vektor bentuk kanonis (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Kapan suatu pembaca atau validator lulus rangkaian pengujian diuraikan dalam deskripsi rangkaian kesesuaian. Pembaca Python ditulis secara independen dari kode referensi dan lulus rangkaian yang sama; Anda dapat menggunakannya sebagai model.
| Tempat | Kegunaannya |
|---|---|
| GitHub: soqvercom/so4ag | Kode, spesifikasi, rangkaian kesesuaian, dan rilis. Di sinilah format dikembangkan. |
| GitHub Discussions | Tempat bagi komunitas: pertanyaan, usulan, dan pengalaman dengan format. Kami menjawab di sini. |
| GitHub Issues | Kesalahan pada spesifikasi dan kode, serta kasus yang tidak dapat dinyatakan oleh format. |
| PyPI: so4ag | Paket Python: pip install so4ag |
| Rilis | Paket JavaScript dan berkas setiap versi: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Tautan permanen ke rilis untuk dikutip dalam makalah dan dokumentasi. |
| MCP Registry | Entri server MCP kami: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Pertanyaan singkat dan percakapan dengan mereka yang mencoba format ini. |
| DEV: @soqvercom | Artikel teknis dan panduan tentang format ini. |
| daily.dev: @soqver | Tautan ke artikel baru untuk pengembang. |
| X · YouTube | Berita tentang format dan demo singkat. |
Menemukan fakta yang tidak dapat dinyatakan oleh format ini, atau dua pembaca yang menjawab berbeda? Tuliskan sebagai isu di GitHub. Mohon laporkan kerentanan melalui surel ke [email protected].