SOQVER إعداد مصدر
العربية

دليل المطوّرين

SO4AG صيغة مفتوحة لحقائق الأعمال: تحمل كل حقيقة معناها ونطاقها وأصلها وصلاحيتها. يجيب القارئ عن سؤال واحد: هل يجوز استخدام هذه الحقيقة لهذه المهمة في هذا الوقت، وإن لم يجز، فلماذا.

التنسيق مجاني ولا يحتاج إلى حساب. الشفرة مرخّصة بموجب Apache-2.0، ونص المواصفة بموجب CC BY 4.0.

كل شيء في مكان واحد

المستودع على GitHub · المواصفات · JSON Schema · مجموعة المطابقة · JSON-LD · أداة التحقق في المتصفح · ما يعمل

المحتويات: 1. احصل على الشيفرة · 2. تحقق من مصدر · 3. اسأل عن حقيقة · 4. انشر مصدرك · 5. API · 6. MCP · 7. قارئك الخاص · أي قطاع · أين تجد المشروع

1. الحصول على الشفرة

تحتاجون إلى 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

2. التحقق من مصدر

تقرأ أداة التحقق ملفًا أو عنوانًا. وهي تفهم 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. وللمصدر غير الصالح تتبع ذلك قائمة بالأخطاء مع موضعها في الملف. ومن دون تثبيت أي شيء يعمل الأمر نفسه في أداة التحقق في المتصفح.

يثبت المصدر الصالح صحة البنية فقط. وهو لا يقول إن الحقيقة صادقة.

3. السؤال عمّا إذا كان يجوز استخدام حقيقة

تبيّن المهمة الخاصية التي تسألون عنها والشروط (النطاق). يعيد القارئ كل ادّعاء مطابق مع الجواب عمّا إذا كان قابلًا للاستخدام، والأسباب حين لا يكون كذلك.

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

جرّبوا الأمر نفسه من دون شرط الفرع أو في وقت آخر (--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يحمل المصدر تصديقًا باسم جهة إصدار تثق بها، لكنك لم توثّقه لدى جهة الإصدار. الاسم المكتوب في المصدر ليس دليلًا.
conflicting_claimsينص ادعاءان ساريان على قيمتين مختلفتين للشيء نفسه. لا يستخدم القارئ أيًا منهما ولا يختار فائزًا بصمت أبدًا.
invalid_sourceيخلّ المصدر ببنية الصيغة (مثل ادعاء بلا دليل أو تاريخ غير قابل للقراءة). لا يُستخدم شيء منه.
unsupported_versionالمصدر بإصدار من الصيغة لا يعرفه القارئ. ولا يُقرأ وفق قواعد إصدار آخر.

القائمة الكاملة للأسباب والقواعد في المواصفات.

4. نشر مصدركم الخاص

المصدر ملف 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"
    }
  ]
}
  1. احفظوا الملف باسم so4ag.json وتحققوا منه بالمدقق (الخطوة 2).
  2. قدّموه عبر HTTPS على نطاقكم عند /so4ag.json بالنوع application/json.
  3. أضيفوا رابطًا إلى المصدر في الصفحات الموجّهة إلى الأشخاص:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. لتضمين الحقائق نفسها داخل الصفحة، حوّلوا المصدر إلى JSON-LD وضعوا النتيجة في وسم <script type="application/ld+json">. والتحويل بلا فقدان.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. امنحوا كل ادّعاء نهاية صلاحية (valid_until) وأكّدوه أو غيّروه قبل انقضائها. وبعد ذلك الوقت يتوقف القرّاء عن استخدامه.

أي قطاع: الملف التعريفي العام وملفكم التعريفي

الصيغة غير مرتبطة بقطاع معيّن. تُحدَّد الخصائص (معنى الحقيقة ونوعها ووحدتها والشروط التي تقيّدها) بملف تعريفي، ويمكن لمصدر واحد أن يستخدم عدة ملفات تعريفية معاً.

ملف التعريفلمن
عامأي نشاط تجاري أو منظمة: المشغّل، والأماكن وساعات العمل، وجهات الاتصال، واللغات، وما يقدّمه وبأي ثمن، والدفع، والحجز، وأوقات الاستجابة والتسليم، والإلغاء، والضمان، وإمكانية الوصول، والتراخيص، والتوفر. 26 خاصية.
تأجير المركبات، تجارة التجزئةما يخص القطاع: العربون وحد المسافة والشحن والإرجاع.
الخاص بكمأي شيء آخر. الملف التعريفي ملف JSON على نطاقكم؛ لا تسألون أحداً ولا تسجّلون شيئاً.

يصف ملفكم التعريفي خصائصكم بالطريقة نفسها التي تصف بها ملفاتنا: التسمية والوصف ونوع القيمة والوحدات والرموز المسموح بها والشروط. أصغر صيغة:

{
  "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. قدّموا الملف عبر HTTPS على العنوان المذكور في id وأضيفوا ذلك العنوان إلى profiles في مصدركم.
  2. اكتبوا خاصية الادعاء على النحو namespace + الاسم، أي https://dental.example/so4ag-profile#emergencySlot.
  3. تحققوا من الملف التعريفي والمصدر:
    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

القارئ الذي لا يعرف ملفك التعريفي يظل يستخدم الادعاء عندما تنص المهمة على شروطه؛ وإذا لم تنص عليها، لا يُستخدم الادعاء. وبذلك تسري قواعد أمان الصيغة على كل ملف تعريفي على السواء. مثال كامل لعيادة أسنان بالملف التعريفي General وملفها التعريفي الخاص موجود في المستودع: general-dental.json. مخطط الملف التعريفي: profile.schema.json.

ألا تفضّلون كتابة الملف يدويًا؟ تعدّ خدمة SOQVER مقترحًا من موقعكم، فتؤكّدون الحقائق وتنشرون المصدر معنا أو تنزّلونه لنطاقكم الخاص: إعداد مصدر.

5. قراءة المصادر المنشورة عبر API

الواجهة للقراءة فقط، ولا تحتاج إلى حساب ولا إلى مفتاح.

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.

6. ربط وكيل عبر MCP

خادم 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"}'

7. كتابة قارئكم الخاص

مجموعة المطابقة هي JSON عادي ولا تحتاج إلى أي من شيفرتنا. تضم مصدرين صالحين في ثلاثة أشكال، وقيم التجزئة المتوقعة للادعاءات، و45 حالة تقييم، و31 حالة تحقق، و10 حالات للمصدر بأكمله، و25 متجهًا للشكل المعياري (RFC 8785).

python readers/python/so4ag_reader.py conformance spec/conformance/0.1

يُوضَّح متى يجتاز قارئ أو مدقّق المجموعة في وصف مجموعة المطابقة. وقد كُتب قارئ Python باستقلال عن الشفرة المرجعية ويجتاز المجموعة نفسها، ويمكنكم اتخاذه نموذجاً.

أين تجدون المشروع

المكانالغرض منه
GitHub: soqvercom/so4agالشيفرة والمواصفات ومجموعة اختبارات المطابقة والإصدارات. هنا تُطوَّر الصيغة.
GitHub Discussionsمكان المجتمع: الأسئلة والاقتراحات والخبرة مع الصيغة. نجيب هنا.
GitHub Issuesأخطاء في المواصفات والشيفرة، وحالات تعجز الصيغة عن التعبير عنها.
PyPI: so4agحزمة Python: pip install so4ag
الإصداراتحزمة JavaScript وملفات كل إصدار: npm install github:soqvercom/so4ag
Zenodo (DOI)رابط دائم إلى الإصدارات للاستشهاد بها في الأوراق والوثائق.
MCP Registryمدخل خادم MCP الخاص بنا: com.soqver/so4ag
Discord: SOQVER · SO4AGأسئلة سريعة ومحادثة مع آخرين يجرّبون الصيغة.
DEV: @soqvercomمقالات تقنية ونصوص إرشادية عن الصيغة.
daily.dev: @soqverروابط إلى مقالات جديدة للمطورين.
X · YouTubeأخبار عن الصيغة وعروض قصيرة.

الملاحظات والأخطاء

هل وجدتم حقيقة لا يستطيع التنسيق التعبير عنها، أو قارئين يجيبان بإجابتين مختلفتين؟ اكتبوها بوصفها مشكلة على GitHub. يُرجى الإبلاغ عن الثغرة بالبريد الإلكتروني إلى [email protected].