В этой статье
Что такое 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, поддерживая синхронизацию серверной валидации и клиентского интерфейса
- Контрактное тестирование в 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, так и для проверки типов на стороне клиента.