SO4AG, işletme olguları için açık bir biçimdir: her olgu anlamını, kapsamını, kökenini ve geçerliliğini taşır. Okuyucu tek bir soruyu yanıtlar: bu olgu bu görev için bu anda kullanılabilir mi; kullanılamazsa neden.
Biçim ücretsizdir ve hesap gerektirmez. Kod Apache-2.0, belirtim metni ise CC BY 4.0 ile lisanslanmıştır.
GitHub'daki depo · belirtim · JSON Schema · uygunluk paketi · JSON-LD · tarayıcıdaki doğrulayıcı · neler çalışır
İçindekiler: 1. Kodu alın · 2. Bir kaynağı doğrulayın · 3. Bir olgu hakkında sorun · 4. Kendi kaynağınızı yayımlayın · 5. API · 6. MCP · 7. Kendi okuyucunuz · Her sektör · Projeyi nerede bulabilirsiniz
Git ve Node.js 20 veya daha yenisine ihtiyacınız vardır. Python okuyucusu yalnızca standart kitaplığı gerektirir (Python 3.10 veya daha yenisi).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
Son komut, referans kodunun testlerini uygunluk paketine karşı çalıştırır. Tümünün geçmesi gerekir.
Paketler kendi projenize her biri tek bir komutla kurulur:
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
Doğrulayıcı bir dosyayı veya bir adresi okur. SO4AG JSON biçimini, JSON-LD biçimini ve içinde JSON-LD bulunan bir HTML sayfasını anlar.
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
Yanıt VALID veya INVALID ile başlar. Geçersiz bir kaynak için dosyadaki yerleriyle birlikte bir hata listesi gelir. Hiçbir şey kurmadan aynı işlem tarayıcıdaki doğrulayıcıda da çalışır.
Geçerli bir kaynak yalnızca yapının doğru olduğunu kanıtlar. Olgunun doğru olduğunu söylemez.
Bir görev, hangi özelliği ve hangi koşullar (kapsam) için sorduğunuzu belirtir. Okuyucu eşleşen her iddiayı, kullanılabilir olup olmadığı yanıtıyla ve kullanılabilir değilse gerekçeleriyle birlikte döndürür.
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
Aynısını şube koşulu olmadan veya başka bir zamanda deneyin (--now 2027-06-01T12:00:00Z; JavaScript'te üçüncü bağımsız değişken { now: new Date(…) }). İddia kullanılabilir olmaktan çıkar ve okuyucu nedenini söyler.
| Gerekçe | Anlamı |
|---|---|
expired, not_yet_valid | İddia, sorunun sorulduğu anda geçerli değildir. |
scope_mismatch:<key> | İddia, koşulun başka bir değeri için geçerlidir; örneğin başka bir şube. |
scope_not_in_task:<key> | İddia, görevin belirtmediği bir koşulla sınırlıdır. Bu koşul olmadan iddianın uygulanıp uygulanmadığı söylenemez. |
unknown, not_applicable | Yayımcı, değerin bilinmediğini veya uygulanmadığını açıkça belirtir. Bilinmeyen, sıfır değildir. |
disputed | İddia ihtilaflıdır. |
no_trust_policy | Görev, incelenmiş bir iddia ister ancak kime güvendiğini belirtmez. Kime güvenileceği, iddiayı okuyanın kararıdır. |
attestation_not_authenticated | Kaynak, güvendiğiniz bir düzenleyenin adını taşıyan bir tasdik içerir; ancak bunu düzenleyen nezdinde doğrulamamışsınızdır. Kaynağa yazılmış bir ad kanıt değildir. |
conflicting_claims | İki güncel iddia aynı şey için farklı değerler belirtir. Okuyucu ikisini de kullanmaz ve asla sessizce bir kazanan seçmez. |
invalid_source | Kaynak, formatın yapısını bozar (örneğin kanıtsız bir iddia veya okunamayan bir tarih). Ondan hiçbir şey kullanılmaz. |
unsupported_version | Kaynak, okuyucunun bilmediği bir biçim sürümündedir. Başka bir sürümün kurallarına göre okunmaz. |
Gerekçelerin ve kuralların tam listesi belirtimde yer alır.
Bir kaynak tek bir JSON dosyasıdır. En küçük kullanışlı biçim bir yayımcı ve bir iddia içerir:
{
"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 olarak kaydedin ve doğrulayıcı ile denetleyin (2. adım)./so4ag.json adresinde application/json türüyle HTTPS üzerinden sunun.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json"> etiketine koyun. Dönüşüm kayıpsızdır. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) verin ve bu süre dolmadan iddiayı onaylayın veya değiştirin. Bu süreden sonra okuyucular iddiayı kullanmayı bırakır.Biçim bir sektöre bağlı değildir. Özellikler (bir olgunun ne anlama geldiği, türü ve birimi ile hangi koşulların onu sınırladığı) bir profil tarafından belirlenir; bir kaynak birkaç profili birlikte kullanabilir.
| Profil | Kimler için |
|---|---|
| Genel | Her işletme veya kuruluş: işletmeci, yerler ve çalışma saatleri, iletişim bilgileri, diller, neler sunduğu ve hangi bedelle, ödeme, rezervasyon, yanıt ve teslim süreleri, iptal, garanti, erişilebilirlik, lisanslar, müsaitlik. 26 özellik. |
| Araç kiralama, Perakende | Sektöre özgü olanlar: depozito, kilometre sınırı, kargo, iadeler. |
| Size ait | Diğer her şey. Profil, etki alanınızdaki bir JSON dosyasıdır; kimseye sormaz, hiçbir kayıt yaptırmazsınız. |
Kendi profiliniz, özelliklerinizi bizimkilerle aynı şekilde tanımlar: etiket, açıklama, değer türü, birimler, izin verilen kodlar ve koşullar. En küçük biçim:
{
"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 içinde verilen adreste HTTPS üzerinden sunun ve bu adresi kaynağınızdaki profiles alanına ekleyin.namespace + ad olarak yazın, yani 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.jsonProfilinizi bilmeyen bir okuyucu, görev koşullarını belirttiğinde iddiayı yine de kullanır; görev belirtmediğinde iddia kullanılmaz. Bu nedenle formatın güvenlik kuralları her profil için aynı şekilde geçerlidir. Genel profili ve kendi profili bulunan bir diş hekimliği muayenehanesinin eksiksiz örneği depodadır: general-dental.json. Bir profilin şeması: profile.schema.json.
Dosyayı elle yazmak istemiyor musunuz? SOQVER hizmeti web sitenizden bir öneri hazırlar; olguları siz onaylarsınız ve kaynağı bizimle yayımlarsınız ya da kendi alan adınız için indirirsiniz: kaynak hazırlayın.
Arayüz salt okunurdur; hesap veya anahtar gerektirmez.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
İlk adres, bir şirketin yayımladığı veya onayladığı kaynakların listesini döndürür. İkincisi, bir kaynağın iddialarını göreviniz için değerlendirir ve her biri için usable ile reasons döndürür. Her kaynak aynı zamanda insanlar için bir sayfa (/s/<slug>/), bir dosya /s/<slug>/so4ag.json ve bir JSON-LD biçimi /s/<slug>/facts.jsonld olarak da sunulur.
MCP sunucusu salt okunurdur, hesap gerektirmez ve Streamable HTTP aktarımını kullanır. Resmi MCP Registry'de com.soqver/so4ag olarak listelenir.
https://soqver.com/mcp
| Araç | Ne yapar |
|---|---|
list_sources | Yayımlanmış kaynakları listeler. |
get_source | Bir işletmenin kaynağının tamamını döndürür. |
get_claims | Bir kaynağın iddialarını, verilen bir özellik ve koşullar için değerlendirir. |
check_claim | Bir iddianın şu anda kullanılıp kullanılamayacağını ve kullanılamıyorsa nedenini belirtir. |
Uzak MCP sunucularını destekleyen bir istemcide yukarıdaki adresi girin. Sunucunun yanıtını komut satırından da denetleyebilirsiniz:
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"}'
Uygunluk paketi düz JSON'dur ve kodumuzun hiçbirine ihtiyaç duymaz. Üç biçimde iki geçerli kaynak, iddiaların beklenen özet değerleri, 45 değerlendirme vakası, 31 doğrulama vakası, 10 tam kaynak vakası ve kanonik biçimin 25 vektörünü (RFC 8785) içerir.
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Bir okuyucunun veya bir doğrulayıcının paketi hangi koşullarda geçtiği, uygunluk paketinin açıklamasında anlatılır. Python okuyucusu referans kodundan bağımsız yazılmıştır ve aynı paketi geçer; örnek olarak kullanabilirsiniz.
| Yer | Ne işe yarar |
|---|---|
| GitHub: soqvercom/so4ag | Kod, belirtim, uygunluk paketi ve sürümler. Biçim burada geliştirilir. |
| GitHub Discussions | Topluluğun yeri: biçime ilişkin sorular, öneriler ve deneyimler. Burada yanıt veririz. |
| GitHub Issues | Belirtimdeki ve koddaki hatalar ile biçimin ifade edemediği durumlar. |
| PyPI: so4ag | Python paketi: pip install so4ag |
| Sürümler | JavaScript paketi ve her sürümün dosyaları: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Makalelerde ve belgelerde atıf için sürümlere kalıcı bağlantı. |
| MCP Registry | MCP sunucumuzun kaydı: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Hızlı sorular ve formatı deneyen diğer kişilerle sohbet. |
| DEV: @soqvercom | Format hakkında teknik makaleler ve nasıl yapılır metinleri. |
| daily.dev: @soqver | Geliştiriciler için yeni makalelere bağlantılar. |
| X · YouTube | Biçim hakkındaki haberler ve kısa demolar. |
Biçimin ifade edemediği bir olgu ya da farklı yanıt veren iki okuyucu mu buldunuz? Bunu GitHub'da bir sorun olarak yazın. Bir güvenlik açığını lütfen [email protected] adresine e-posta ile bildirin.