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. אימות מקור

המאמת קורא קובץ או כתובת. הוא מבין JSON של SO4AG, את צורת 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].