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
המאמת קורא קובץ או כתובת. הוא מבין 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. במקור לא תקין מופיעה אחר כך רשימת שגיאות עם מקומן בקובץ. בלי להתקין דבר, אותו דבר פועל במאמת בדפדפן.
מקור תקין מוכיח מבנה נכון בלבד. הוא אינו אומר שהעובדה נכונה.
משימה מציינת איזה מאפיין אתם שואלים ובאילו תנאים (היקף). הקורא מחזיר כל טענה תואמת עם התשובה אם היא ניתנת לשימוש, ואת הסיבות כשאינה ניתנת לשימוש.
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].