У цій статті
Що таке JSON Schema?
JSON Schema — це словник для анотування та перевірки JSON-документів. Він визначає структуру, типи та обмеження, яким повинен відповідати JSON-документ. Уявіть це як контракт — схема описує, як виглядають дійсні дані, а валідатори перевіряють, чи відповідає документ цьому контракту.
JSON Schema написана в самому JSON, що робить її машиночитаємою та незалежною від мови. Вона підтримується валідаторами в усіх основних мовах програмування (JavaScript/Ajv, Python/jsonschema, Java/everit, Go/gojsonschema) і використовується для перевірки API, файлів конфігурації та генерації форм.
Основи JSON Schema
Основні ключові слова визначають форму дійсних JSON-документів.
- type — вказує дозволений тип JSON: string, number, integer, boolean, object, array або null. Найбільш фундаментальне обмеження.
- properties та required — для об'єктів 'properties' визначає схему кожного поля, а 'required' перераховує, які поля повинні бути присутніми. Поля, відсутні в 'required', за замовчуванням є необов'язковими.
- enum та const — 'enum' обмежує значення фіксованим набором варіантів, тоді як 'const' обмежує його до одного точного значення. Корисно для полів статусу, категорій та параметрів конфігурації.
- pattern та format — 'pattern' перевіряє рядки відносно регулярного виразу. 'format' забезпечує семантичну перевірку, як 'email', 'uri', 'date-time' та 'ipv4' без регулярних виразів.
Ці основні ключові слова охоплюють більшість потреб перевірки. Проста схема може визначати тип об'єкта з обов'язковою властивістю 'name' (рядок) та необов'язковою 'age' (ціле число, мінімум 0).
Розширені можливості схем
Для складних вимог перевірки JSON Schema пропонує композицію, посилання та умовну логіку.
- $ref посилання — повторно використовуйте визначення схем, посилаючись на них за допомогою $ref. Вказуйте на визначення в тому ж документі ($ref: #/$defs/Address) або зовнішніх файлах. Усуває дублювання в великих схемах.
- allOf / anyOf / oneOf — ключові слова композиції, що поєднують кілька схем. 'allOf' вимагає відповідності всіх підсхем, 'anyOf' вимагає принаймні однієї, а 'oneOf' вимагає рівно однієї. Корисно для поліморфних типів.
- if / then / else — умовні схеми, що застосовують різні правила перевірки залежно від значень даних. Наприклад, якщо країна 'US', то поштовий індекс повинен відповідати 5-значному шаблону, інакше дозволити будь-який формат.
- additionalProperties — контролює, чи може об'єкт містити властивості, не перераховані в 'properties'. Встановіть false для суворої перевірки або до схеми для обмеження додаткових властивостей.
Спробуйте безкоштовно — реєстрація не потрібна
Валідувати JSON Schema →Версії чернеток схем
JSON Schema еволюціонувала через кілька чернеткових версій, кожна з яких додавала нові функції та вдосконалювала існуючу поведінку.
- Draft-04 — перша широко прийнята версія. Введено $ref, required як масив та основні ключові слова перевірки. Досі використовується в багатьох застарілих системах та OpenAPI 3.0.
- Draft-06 — додано ключове слово const, propertyNames, contains для масивів та булеві схеми (true/false як дійсні схеми). Незначні, але корисні доповнення.
- Draft-07 — додано умовну логіку if/then/else, анотації readOnly/writeOnly та ключові слова кодування вмісту. Найпопулярніша чернеткова версія сьогодні.
- 2019-09 (Draft 2019-09) — major реструктуризація. Введено $defs (замінює definitions), $anchor, unevaluatedProperties та систему словників. Краще для великомасштабного дизайну схем.
- 2020-12 (Draft 2020-12) — остання стабільна чернетка. Вдосконалено динамічні посилання, додано prefixItems для перевірки кортежів (замінює items як масив) та покращено формати виводу. Рекомендовано для нових проектів.
Поширені варіанти використання
JSON Schema використовується скрізь, де потрібно перевіряти або документувати JSON-дані.
- Перевірка API — перевіряйте тіла запитів та параметри запиту відносно схем у middleware Express/Fastify. Специфікації OpenAPI/Swagger вбудовують JSON Schema для визначення контракту API.
- Перевірка конфігурації — перевіряйте файли конфігурації додатків (JSON, YAML, конвертований у JSON) під час запуску. Виявляйте помилки друку та відсутні поля до того, як вони спричинять помилки під час виконання.
- Генерація форм — інструменти, як react-jsonschema-form та vue-jsonschema-form, автоматично генерують HTML-форми з визначень JSON Schema, включаючи правила перевірки та UI-віджети.
- Генерація коду — генеруйте інтерфейси TypeScript, структури Go або dataclasses Python з визначень JSON Schema. Зберігає типи в синхронізації з API-контрактами.
Поширені помилки валідації
При перевірці JSON відносно схеми, це найбільш поширені помилки, з якими ви зіткнетесь.
- Невідповідність типу — тип значення не відповідає обмеженню 'type' схеми. Поширені приклади: рядок там, де очікується число, null для поля, що не може бути null, або об'єкт там, де потрібен масив.
- Відсутні обов'язкові поля — у JSON-об'єкті відсутня властивість, зазначена у масиві 'required'. Валідатори повідомляють, яке конкретне поле відсутнє.
- Помилка шаблону — рядкове значення не відповідає регулярному виразу 'pattern'. Це часто виявляє невалідні формати email, номерів телефонів або власних ідентифікаторів, які не відповідають очікуваному шаблону.
- Помилка розіменування $ref — схема посилається на іншу схему через $ref, яку не вдається знайти. Це відбувається, коли запис $defs відсутній, шлях неправильний або зовнішні файли схеми недоступні.
Часті запитання
Який чернетковий варіант JSON Schema слід використовувати для нових проєктів?
Використовуйте Draft 2020-12 для нових проєктів, якщо у вас немає обмежень. Він має найбільше функцій (prefixItems для кортежів, unevaluatedProperties, динамічні посилання) та найвищу якість специфікації. Якщо вам потрібна сумісність з OpenAPI 3.0 — використовуйте Draft-04. Якщо вам потрібна найширша підтримка бібліотек, Draft-07 є найбезпечнішим вибором — майже кожен валідатор підтримує його.
Як повторно використовувати схеми в кількох файлах?
Використовуйте $ref для посилання на схеми за URI. Для локальних визначень розміщуйте схеми, що повторно використовуються, у $defs того ж файлу та посилайтеся на них через $ref: '#/$defs/SchemaName'. Для міжфайлових посилань використовуйте відносні URI ($ref: './address.json') або абсолютні URI. Більшість валідаторів підтримують як локальне, так і віддалене розіменування $ref.
Чи може JSON Schema валідувати вкладені об'єкти?
Так. Визначайте вкладені схеми у 'properties' батьківського об'єкта. Кожна вкладена властивість може мати власний тип, обов'язкові поля та правила валідації. Для глибоко вкладених структур використовуйте $ref для збереження читабельності схеми. Глибина вкладеності не обмежена — валідатор рекурсивно перевіряє кожен рівень.