SOQVER Siapkan sumber
Bahasa Indonesia

Panduan untuk pengembang

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.

Semua di satu tempat

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

1. Dapatkan kodenya

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

2. Validasi sumber

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.

3. Tanyakan apakah suatu fakta boleh digunakan

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.

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

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.

AlasanArtinya
expired, not_yet_validKlaim 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_applicablePenerbit menyatakan secara eksplisit bahwa nilai tidak diketahui atau tidak berlaku. Tidak diketahui bukan berarti nol.
disputedKlaim disengketakan.
no_trust_policyTugas meminta klaim yang telah ditinjau, tetapi tidak menyatakan pihak yang dipercayainya. Pihak yang dipercaya merupakan keputusan pihak yang membaca klaim.
attestation_not_authenticatedSumber memuat atestasi dengan nama penerbit yang Anda percayai, tetapi Anda belum mengautentikasinya dengan penerbit tersebut. Nama yang tertulis dalam sumber bukan bukti.
conflicting_claimsDua klaim yang berlaku menyatakan nilai yang berbeda untuk hal yang sama. Pembaca tidak menggunakan keduanya dan tidak pernah memilih pemenang secara diam-diam.
invalid_sourceSumber melanggar struktur format (misalnya klaim tanpa bukti atau tanggal yang tidak terbaca). Tidak ada bagiannya yang digunakan.
unsupported_versionSumber menggunakan versi format yang tidak dikenal pembaca. Sumber tidak dibaca menurut aturan versi lain.

Daftar lengkap alasan dan aturan terdapat dalam spesifikasi.

4. Terbitkan sumber Anda sendiri

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"
    }
  ]
}
  1. Simpan berkas sebagai so4ag.json dan periksa dengan validator (langkah 2).
  2. Sajikan melalui HTTPS di domain Anda pada /so4ag.json dengan tipe application/json.
  3. Tambahkan tautan ke sumber pada halaman untuk orang:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Agar fakta yang sama ada di dalam halaman, ubah sumber menjadi JSON-LD dan masukkan hasilnya ke tag <script type="application/ld+json">. Konversi ini tanpa kehilangan data.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Berikan setiap klaim akhir masa berlaku (valid_until) serta konfirmasikan atau ubah klaim sebelum waktu itu terlewati. Setelah waktu tersebut, pembaca berhenti menggunakannya.

Industri apa pun: profil General dan profil Anda sendiri

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.

ProfilUntuk siapa
GeneralSetiap 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, RitelHal yang khusus bagi industri: deposit, batas jarak tempuh, pengiriman, pengembalian.
Milik AndaHal 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."
    }
  }
}
  1. Sajikan berkas melalui HTTPS pada alamat yang tercantum di id dan tambahkan alamat tersebut ke profiles pada sumber Anda.
  2. Tuliskan properti suatu klaim sebagai namespace + nama, yaitu https://dental.example/so4ag-profile#emergencySlot.
  3. Periksa profil dan sumber:
    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

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

5. Baca sumber yang diterbitkan melalui API

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.

6. Hubungkan agen melalui MCP

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
AlatFungsinya
list_sourcesMenampilkan daftar sumber yang diterbitkan.
get_sourceMengembalikan seluruh sumber dari satu bisnis.
get_claimsMengevaluasi klaim suatu sumber untuk properti dan kondisi yang diberikan.
check_claimMenyatakan 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"}'

7. Tulis pembaca Anda sendiri

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.

Di mana menemukan proyek

TempatKegunaannya
GitHub: soqvercom/so4agKode, spesifikasi, rangkaian kesesuaian, dan rilis. Di sinilah format dikembangkan.
GitHub DiscussionsTempat bagi komunitas: pertanyaan, usulan, dan pengalaman dengan format. Kami menjawab di sini.
GitHub IssuesKesalahan pada spesifikasi dan kode, serta kasus yang tidak dapat dinyatakan oleh format.
PyPI: so4agPaket Python: pip install so4ag
RilisPaket JavaScript dan berkas setiap versi: npm install github:soqvercom/so4ag
Zenodo (DOI)Tautan permanen ke rilis untuk dikutip dalam makalah dan dokumentasi.
MCP RegistryEntri server MCP kami: com.soqver/so4ag
Discord: SOQVER · SO4AGPertanyaan singkat dan percakapan dengan mereka yang mencoba format ini.
DEV: @soqvercomArtikel teknis dan panduan tentang format ini.
daily.dev: @soqverTautan ke artikel baru untuk pengembang.
X · YouTubeBerita tentang format dan demo singkat.

Umpan balik dan kesalahan

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