SOQVER Kaynak hazırlayın
Türkçe

Geliştiriciler için kılavuz

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.

Her şey tek yerde

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

1. Kodu edinin

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

2. Bir kaynağı doğrulayın

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.

3. Bir olgunun kullanılıp kullanılamayacağını sorun

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.

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

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çeAnlamı
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_applicableYayı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_policyGörev, incelenmiş bir iddia ister ancak kime güvendiğini belirtmez. Kime güvenileceği, iddiayı okuyanın kararıdır.
attestation_not_authenticatedKaynak, 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_sourceKaynak, formatın yapısını bozar (örneğin kanıtsız bir iddia veya okunamayan bir tarih). Ondan hiçbir şey kullanılmaz.
unsupported_versionKaynak, 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.

4. Kendi kaynağınızı yayımlayın

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"
    }
  ]
}
  1. Dosyayı so4ag.json olarak kaydedin ve doğrulayıcı ile denetleyin (2. adım).
  2. Bunu kendi alan adınızda /so4ag.json adresinde application/json türüyle HTTPS üzerinden sunun.
  3. Kişilere yönelik sayfalara kaynağın bağlantısını ekleyin:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Aynı olguların sayfanın içinde bulunması için kaynağı JSON-LD biçimine dönüştürün ve sonucu bir <script type="application/ld+json"> etiketine koyun. Dönüşüm kayıpsızdır.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Her iddiaya bir geçerlilik sonu (valid_until) verin ve bu süre dolmadan iddiayı onaylayın veya değiştirin. Bu süreden sonra okuyucular iddiayı kullanmayı bırakır.

Her sektör: Genel profil ve kendi profiliniz

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.

ProfilKimler için
GenelHer 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, PerakendeSektöre özgü olanlar: depozito, kilometre sınırı, kargo, iadeler.
Size aitDiğ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."
    }
  }
}
  1. Dosyayı id içinde verilen adreste HTTPS üzerinden sunun ve bu adresi kaynağınızdaki profiles alanına ekleyin.
  2. Bir iddianın özelliğini namespace + ad olarak yazın, yani https://dental.example/so4ag-profile#emergencySlot.
  3. Profili ve kaynağı denetleyin:
    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

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

5. Yayımlanmış kaynakları API üzerinden okuyun

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.

6. Bir ajanı MCP üzerinden bağlayın

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_sourcesYayımlanmış kaynakları listeler.
get_sourceBir işletmenin kaynağının tamamını döndürür.
get_claimsBir kaynağın iddialarını, verilen bir özellik ve koşullar için değerlendirir.
check_claimBir 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"}'

7. Kendi okuyucunuzu yazın

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.

Projeyi nerede bulabilirsiniz

YerNe işe yarar
GitHub: soqvercom/so4agKod, belirtim, uygunluk paketi ve sürümler. Biçim burada geliştirilir.
GitHub DiscussionsTopluluğun yeri: biçime ilişkin sorular, öneriler ve deneyimler. Burada yanıt veririz.
GitHub IssuesBelirtimdeki ve koddaki hatalar ile biçimin ifade edemediği durumlar.
PyPI: so4agPython paketi: pip install so4ag
SürümlerJavaScript 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 RegistryMCP sunucumuzun kaydı: com.soqver/so4ag
Discord: SOQVER · SO4AGHızlı sorular ve formatı deneyen diğer kişilerle sohbet.
DEV: @soqvercomFormat hakkında teknik makaleler ve nasıl yapılır metinleri.
daily.dev: @soqverGeliştiriciler için yeni makalelere bağlantılar.
X · YouTubeBiçim hakkındaki haberler ve kısa demolar.

Geri bildirim ve hatalar

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.