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 |
| Платформа вимагає версію | Деякі low-code платформи й шлюзи її закріплюють |
| Генератори коду, що зупиняються на 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, тож той самий файл може перевірятися по-різному в двох місцях.