draft-07 یا 2020-12
جمع‌بندی: 2020-12 نسخه کنونی است و $defs، prefixItems و unevaluatedProperties را اضافه میکند، اما بسیاری ابزارها همچنان فقط draft-07 را می‌فهمند. بر اساس پشتیبانی کل زنجیره ابزارتان انتخاب کنید.
جمع‌بندی: برای پروژههای جدید از 2020-12 استفاده کنید، به‌محض اینکه هر اعتبارسنج، تولیدکننده کد یا ابزار OpenAPI فقط آن را پشتیبانی کند به draft-07 برگردید، و همیشه draft را با $schema سنجاق کنید.
پاسخ کوتاه: 2020-12 برای کار جدید، draft-07 وقتی یک جزء قدیمی مجبورش میکند.
خط زمانی
| Draft | سال | قابل توجه |
|---|---|---|
| draft-04 | ۲۰۱۳ | id به‌جای $id؛ در APIهای قدیمی همچنان رایج |
| draft-06 | ۲۰۱۷ | const، propertyNames |
| draft-07 | ۲۰۱۸ | if/then/else، readOnly، contentMediaType؛ بهترین سازگاری |
| 2019-09 | ۲۰۱۹ | $defs جایگزین definitions، unevaluatedProperties |
| 2020-12 | ۲۰۲۰ | prefixItems، $dynamicRef؛ توصیه کنونی |
2020-12 چه چیزی را بهبود می‌دهد
tupleهای آرایه دیگر حالت خاص نیستند. draft-07 «عنصر اول A است، دوم B» را با items: [{...}, {...}] به‌علاوه additionalItems بیان میکند. 2020-12 از prefixItems برای schemaهای موقعیت‌محور و از items برای بقیه استفاده میکند.
$defs نام استاندارد است. ابزارهای نوشته‌شده بعد از ۲۰۱۹ به‌صورت پیش‌فرض آنجا را نگاه می‌کنند.
unevaluatedProperties با ترکیب کار میکند. با allOf، additionalProperties: false فیلدهای تعریف‌شده در شاخه‌های همسایه را رد میکند. unevaluatedProperties: false فقط ویژگی‌هایی را در نظر می‌گیرد که کل schema واقعاً ارزیابی کرده، که همان چیزی است که ترکیب لازم دارد.
چه زمانی draft-07 پاسخ درست است
| موقعیت | دلیل |
|---|---|
| OpenAPI 3.0 | شیء schema آن زیرمجموعه draft-04/07 است |
| اعتبارسنج‌های قدیمی (ajv 6، برخی کتابخانه‌های Java) | prefixItems یا $dynamicRef را نمی‌شناسند |
| پلتفرم نسخه‌ای را تحمیل میکند | برخی پلتفرم‌های low-code و دروازه‌ها آن را سنجاق می‌کنند |
| تولیدکننده‌های کدی که در 07 متوقف می‌شوند | کلیدواژههای ناشناخته بیصدا نادیده گرفته می‌شوند |
مورد آخر را مستقیم آزمایش کنید: schemaای با 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 از draftها عبور نکنید. رفتار تعریف‌نشده است.
دسته‌دسته ارتقا دهید. دو draft در یک مخزن «کدام قواعد اینجا اعمال می‌شوند» را به دانش قبیله‌ای تبدیل میکند.
پرسش‌های متداول
چگونه بررسی کنم اعتبارسنجم از 2020-12 پشتیبانی میکند؟
schemaای استفاده‌کننده از prefixItems به اعتبارسنج بدهید. خطای کلیدواژه ناشناخته یعنی draft را پشتیبانی نمی‌کند؛ پاس شدن بیصدا یعنی محدودیت را نادیده می‌گیرد که بدتر است.
چرا یک پروژه باید از یک draft واحد استفاده کند؟
دو draft در یک مخزن «کدام قواعد اینجا اعمال می‌شوند» را به دانش قبیله‌ای تبدیل میکند. دسته‌دسته ارتقا دهید تا هر فایل تفسیر یکسان داشته باشد.
آیا باید همیشه $schema را اعلام کنم؟
بله. پیش‌فرض‌ها متفاوت‌اند: ajv فرض draft-07 دارد در حالی که چند کتابخانه Python فرض 2020-12، پس همان فایل می‌تواند در دو جا متفاوت اعتبارسنجی شود.