SO4AG صيغة مفتوحة لحقائق الأعمال: تحمل كل حقيقة معناها ونطاقها وأصلها وصلاحيتها. يجيب القارئ عن سؤال واحد: هل يجوز استخدام هذه الحقيقة لهذه المهمة في هذا الوقت، وإن لم يجز، فلماذا.
التنسيق مجاني ولا يحتاج إلى حساب. الشفرة مرخّصة بموجب Apache-2.0، ونص المواصفة بموجب CC BY 4.0.
المستودع على GitHub · المواصفات · JSON Schema · مجموعة المطابقة · JSON-LD · أداة التحقق في المتصفح · ما يعمل
المحتويات: 1. احصل على الشيفرة · 2. تحقق من مصدر · 3. اسأل عن حقيقة · 4. انشر مصدرك · 5. API · 6. MCP · 7. قارئك الخاص · أي قطاع · أين تجد المشروع
تحتاجون إلى 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
تقرأ أداة التحقق ملفًا أو عنوانًا. وهي تفهم 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. وللمصدر غير الصالح تتبع ذلك قائمة بالأخطاء مع موضعها في الملف. ومن دون تثبيت أي شيء يعمل الأمر نفسه في أداة التحقق في المتصفح.
يثبت المصدر الصالح صحة البنية فقط. وهو لا يقول إن الحقيقة صادقة.
تبيّن المهمة الخاصية التي تسألون عنها والشروط (النطاق). يعيد القارئ كل ادّعاء مطابق مع الجواب عمّا إذا كان قابلًا للاستخدام، والأسباب حين لا يكون كذلك.
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
جرّبوا الأمر نفسه من دون شرط الفرع أو في وقت آخر (--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 | المصدر بإصدار من الصيغة لا يعرفه القارئ. ولا يُقرأ وفق قواعد إصدار آخر. |
القائمة الكاملة للأسباب والقواعد في المواصفات.
المصدر ملف 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"
}
]
}
so4ag.json وتحققوا منه بالمدقق (الخطوة 2)./so4ag.json بالنوع application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. والتحويل بلا فقدان. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_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."
}
}
}
id وأضيفوا ذلك العنوان إلى profiles في مصدركم.namespace + الاسم، أي 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.jsonالقارئ الذي لا يعرف ملفك التعريفي يظل يستخدم الادعاء عندما تنص المهمة على شروطه؛ وإذا لم تنص عليها، لا يُستخدم الادعاء. وبذلك تسري قواعد أمان الصيغة على كل ملف تعريفي على السواء. مثال كامل لعيادة أسنان بالملف التعريفي General وملفها التعريفي الخاص موجود في المستودع: general-dental.json. مخطط الملف التعريفي: profile.schema.json.
ألا تفضّلون كتابة الملف يدويًا؟ تعدّ خدمة SOQVER مقترحًا من موقعكم، فتؤكّدون الحقائق وتنشرون المصدر معنا أو تنزّلونه لنطاقكم الخاص: إعداد مصدر.
الواجهة للقراءة فقط، ولا تحتاج إلى حساب ولا إلى مفتاح.
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.
خادم 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"}'
مجموعة المطابقة هي 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].