draft-07 או 2020-12
שורה תחתונה: 2020-12 הוא העדכני ומוסיף `$defs`, `prefixItems` ו-`unevaluatedProperties`, אבל כלים רבים עדיין מדברים רק draft-07. בחרו לפי מה שכל שרשרת הכלים שלכם תומכת בו.
שורה תחתונה: השתמשו ב-2020-12 לפרויקטים חדשים, חזרו ל-draft-07 ברגע שמאמת, מחולל קוד או כלי OpenAPI תומך רק בו, ותמיד נעלו את ה-draft עם $schema.
תשובה קצרה: 2020-12 לעבודה חדשה, draft-07 כשרכיב ישן מכריח.
ציר זמן
| Draft | שנה | בולט |
|---|---|---|
| draft-04 | 2013 | id במקום $id; עדיין נפוץ ב-API ישנים |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; התאימות הטובה ביותר |
| 2019-09 | 2019 | $defs מחליף את definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; ההמלצה העדכנית |
מה 2020-12 משפר
מערכים מסוג tuple מפסיקים להיות מקרה מיוחד. draft-07 מבטא "האיבר הראשון הוא A, השני הוא B" עם items: [{...}, {...}] ועוד additionalItems. 2020-12 משתמש ב-prefixItems עבור סכמות תלויות-מיקום וב-items לכל השאר.
$defs הוא השם התקני. כלים שנכתבו אחרי 2019 מחפשים שם כברירת מחדל.
unevaluatedProperties עובד עם הרכבה. עם allOf, additionalProperties: false דוחה שדות שמוגדרים בענפים אחים. unevaluatedProperties: false מתחשב רק במאפיינים שהוערכו בפועל על ידי הסכימה כולה, וזה מה שהרכבה צריכה.
מתי draft-07 הוא התשובה הנכונה
| מצב | סיבה |
|---|---|
| OpenAPI 3.0 | אובייקט הסכמה שלו הוא תת-קבוצה של draft-04/07 |
| מאמתים ישנים (ajv 6, כמה ספריות Java) | הם לא מכירים prefixItems או $dynamicRef |
| פלטפורמה מחייבת גרסה | כמה פלטפורמות low-code ו-gateways נועלות אותה |
| מחוללי קוד שעוצרים ב-07 | מילות מפתח לא מוכרות מותעלמות בשקט |
בדקו את המקרה האחרון ישירות: האכילו את המאמת בסכמה שמשתמשת ב-prefixItems. אם היא עוברת בלי תלונה במקום לדווח על מילת מפתח לא מוכרת, הוא מתעלם מהאילוץ — התוצאה המסוכנת מכולן.
ערבוב גרסאות
תמיד הצהירו על $schema. ברירות המחדל שונות: ajv מניח draft-07, כמה ספריות Python מניחות 2020-12. אותו קובץ אז עובר אימות אחר בשני מקומות.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
אל תעשו $ref בין drafts. ההתנהגות אינה מוגדרת.
שדרגו בקבוצות. שני drafts במאגר אחד הופכים את "אילו כללים חלים כאן" לידע שבשפה.
שאלות ותשובות
איך בודקים אם המאמת שלי תומך ב-2020-12?
האכילו את המאמת בסכמה שמשתמשת ב-prefixItems. שגיאת מילת מפתח לא מוכרת פירושה שהוא לא תומך ב-draft; מעבר בשקט פירושו שהוא מתעלם מהאילוץ, וזה גרוע יותר.
למה פרויקט אחד צריך להשתמש ב-draft אחד בלבד?
שני drafts במאגר אחד הופכים את "אילו כללים חלים כאן" לידע שבשפה. שדרגו בקבוצות כך שכל קובץ חולק את אותה פרשנות.
האם תמיד צריך להצהיר על $schema?
כן. ברירות המחדל שונות: ajv מניח draft-07 בעוד כמה ספריות Python מניחות 2020-12, כך שאותו קובץ יכול לעבור אימות אחר בשני מקומות.