У цій статті
Що таке JSON Schema?
JSON Schema — це словник, що дозволяє описувати структуру та правила валідації для JSON-даних. Написана в самому JSON, схема визначає, які властивості може мати об'єкт, які типи дозволені, які поля обов'язкові та які обмеження застосовуються — перетворюючи неформальні контракти даних у машиночитані специфікації.
Найбільш використовувана версія — Draft-07, хоча новіші версії (2019-09, 2020-12) додають функції, такі як умовні схеми та динамічні посилання. Генератор JSON Schema автоматизує трудомісткий процес ручного написання схем — він аналізує зразкові JSON-дані та автоматично визначає типи, структуру та обов'язкові поля.
Як працює генерація схем
Генератор схем аналізує ваш зразковий JSON та створює схему, яка б його валідувала. Процес включає виведення типів, аналіз структури та виявлення обмежень.
- Виведення типів — кожне значення перевіряється для визначення його JSON-типу (string, number, integer, boolean, null, array, object), і схема призначає відповідне ключове слово типу
- Аналіз вкладеної структури — об'єкти рекурсивно аналізуються для генерації підсхем для кожної властивості, а масиви перевіряються для виведення схеми елементів з їхнього вмісту
- Виявлення обов'язкових полів — усі властивості, наявні у зразку, зазвичай позначаються як обов'язкові, оскільки генератор передбачає, що зразок представляє повний дійсний екземпляр
Спробуйте безкоштовно — реєстрація не потрібна
Згенерувати JSON Schema →Коли використовувати JSON Schema
JSON Schema є фундаментальним інструментом для будь-якого проекту, що надсилає або отримує JSON-дані.
- Валідація API-запитів — валідуйте вхідні дані відповідно до схеми перед обробкою, відхиляючи неправильно сформовані запити на ранньому етапі та надаючи зрозумілі повідомлення про помилки споживачам API
- Генерація форм — UI-бібліотеки, такі як react-jsonschema-form та vue-form-generator, можуть автоматично створювати форми з JSON Schema, тримаючи бекенд-валідацію та фронтенд-UI синхронізованими
- Контрактне тестування в CI/CD — перевіряйте, що відповіді API відповідають очікуваній схемі в інтеграційних тестах, виявляючи критичні зміни до того, як вони потраплять у продакшн
Поширені запитання
Яку версію draft JSON Schema використовувати?
Draft-07 — найбезпечніший вибір для широкої сумісності — більшість валідаторів, генераторів форм та генераторів коду повністю його підтримують. Використовуйте 2020-12, якщо потрібні розширені функції, такі як $dynamicRef, prefixItems або unevaluatedProperties. Завжди перевіряйте, чи підтримує ваша бібліотека валідації обраний draft.
Як поєднати кілька схем?
JSON Schema надає ключові слова композиції: allOf вимагає відповідності всіх підсхем, anyOf вимагає відповідності хоча б однієї, а oneOf вимагає відповідності рівно однієї. Використовуйте $ref для посилання на багаторазові визначення схем. Наприклад, схема User може використовувати allOf для поєднання базової PersonSchema з додатковими полями автентифікації.
Чи можна згенерувати типи TypeScript з JSON Schema?
Так. Інструменти, такі як json-schema-to-typescript та quicktype, конвертують JSON Schemas в інтерфейси TypeScript, забезпечуючи синхронізацію фронтенд-типів з бекенд-контрактами. Це особливо корисно в монорепозиторіях, де схема служить єдиним джерелом істини як для валідації API, так і для перевірки типів на стороні клієнта.