draft-07 أم 2020-12
الخلاصة: 2020-12 هو الإصدار الحالي ويضيف $defs وprefixItems وunevaluatedProperties، لكن أدوات كثيرة ما زالت تتحدث draft-07 فقط. اختر وفق ما تدعمه سلسلة أدواتك بأكملها.
الخلاصة: استخدم 2020-12 للمشاريع الجديدة، وعُد إلى draft-07 في اللحظة التي يدعمه فيها فقط أي مدقق أو مولد كود أو أداة OpenAPI، وثبّت الإصدار دائمًا بـ$schema.
جواب قصير: 2020-12 للعمل الجديد، وdraft-07 عندما يفرضه مكوّن قديم.
الخط الزمني
| الإصدار | السنة | أبرز ما فيه |
|---|---|---|
| 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
تتوقف صفوف المصفوفات عن كونها حالة خاصة. يعبر 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 |
| تفرض منصة إصدارًا معينًا | بعض منصات قليلة الكود والبوابات تثبته |
| مولدات الكود التي تتوقف عند 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 عبر الإصدارات. السلوك غير معرّف.
قم بالترقية على دفعات. إصداران في مستودع واحد يحولان سؤال «أي قواعد تنطبق هنا» إلى معرفة شفهية.
الأسئلة الشائعة
كيف أفحص هل يدعم مدققي 2020-12؟
مرّر مخططًا يستخدم prefixItems إلى المدقق. خطأ الكلمة المفتاحية المجهولة يعني أنه لا يدعم الإصدار؛ أما النجاح الصامت فيعني أنه يتجاهل القيد، وهذا أسوأ.
لماذا ينبغي أن يستخدم مشروع واحد إصدارًا واحدًا؟
إصداران في مستودع واحد يحولان سؤال «أي قواعد تنطبق هنا» إلى معرفة شفهية. قم بالترقية على دفعات ليشترك كل ملف في التفسير نفسه.
هل يجب أن أعلن $schema دائمًا؟
نعم. تختلف القيم الافتراضية: يفترض ajv أن draft-07 بينما تفترض عدة مكتبات Python أن 2020-12، لذا يمكن أن يُحلَّل الملف نفسه بطريقتين مختلفتين في مكانين.