Валидация JSON Schema: Полное руководство по определению и проверке данных JSON
Узнайте, как JSON Schema работает в качестве контракта для ваших данных -- от базовых типов и обязательных полей до валидации форматов, версий черновиков и реальных сценариев использования для API и конфигурационных файлов.
Что такое JSON Schema?
JSON Schema -- это декларативный язык, позволяющий описывать структуру, содержимое и ограничения JSON-документа. Представьте его как контракт между производителем и потребителем данных. Производитель говорит: "Я всегда буду отправлять объект со строкой name и целым числом age", а потребитель может проверить, что каждый входящий payload действительно соответствует этому обещанию перед обработкой.
Это важно, потому что сам JSON не имеет схемы. Любое допустимое значение JSON совершенно легально. Эта свобода прекрасна для быстрого прототипирования, но становится проблемой, когда двум системам нужно договориться о том, как должны выглядеть данные.
Почему JSON Schema важна для API
REST API общаются через JSON-payload, и каждый endpoint имеет подразумеваемую форму. JSON Schema делает эту форму явной и машиночитаемой. Имея схему, вы можете:
- Валидировать запросы на сервере до того, как они достигнут бизнес-логики.
- Валидировать ответы в интеграционных тестах для обнаружения ломающих изменений.
- Генерировать документацию автоматически -- такие инструменты как Swagger/OpenAPI используют JSON Schema в качестве основы.
- Генерировать код -- инструменты преобразования схемы в TypeScript, Go-структуры, Python-dataclass устраняют ручное определение типов.
Основы JSON Schema
Каждая JSON Schema сама по себе является объектом JSON. Простейшая возможная схема -- это пустой объект {}, принимающий любой валидный JSON.
Примитивные типы
Ключевое слово type -- это фундамент. JSON Schema распознаёт шесть примитивных типов:
| Тип | Пример JSON | Примечания |
|---|---|---|
| string | "привет" | Текстовые значения. Ограничивается через minLength, maxLength, pattern. |
| number | 3.14 | Любое числовое значение. Используйте minimum, maximum, multipleOf. |
| integer | 42 | Только целые числа. Те же ограничения, что и number. |
| boolean | true | Только true или false. |
| object | {"ключ": "значение"} | Пары ключ-значение. Определяется через properties, required, additionalProperties. |
| array | [1, 2, 3] | Упорядоченные списки. Используйте items, minItems, maxItems, uniqueItems. |
| null | null | Отсутствие значения. Часто комбинируется с другим типом. |
Свойства и обязательные поля
Ключевое слово properties определяет, какие ключи ожидаются. Ключевое слово required перечисляет, какие из них должны присутствовать.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"email": { "type": "string", "format": "email" },
"age": { "type": "integer", "minimum": 0 }
},
"required": ["name", "email"]
}Контроль дополнительных свойств
"additionalProperties": false делает схему строгой -- допускаются только перечисленные ключи.
additionalProperties: false вместе с ключевыми словами композиции вроде allOf, свойства, определённые в других подсхемах, могут быть отклонены. Это одна из самых распространённых ловушек в JSON Schema.
Валидация форматов
Ключевое слово format обеспечивает семантическую валидацию помимо базовых типов.
Встроенные форматы
| Формат | Пример значения | Сценарий использования |
|---|---|---|
| date-time | 2026-03-27T10:30:00Z | Временные метки ISO 8601 для событий и логов |
| date | 2026-03-27 | Календарные даты без времени |
[email protected] | Контактные формы, регистрация пользователей | |
| uri | https://example.com/api | URL вебхуков, ссылки на ресурсы |
| uuid | 550e8400-e29b-41d4-a716-446655440000 | Уникальные идентификаторы, первичные ключи |
| ipv4 | 192.168.1.1 | Сетевая конфигурация, адреса серверов |
Формат как аннотация vs утверждение
По умолчанию format является аннотацией, а не утверждением. В Draft 2020-12 необходимо явно включить утверждение формата.
format с регулярным выражением pattern, если строгая валидация критична.
Версии черновиков: Draft-07 vs 2020-12
Две версии, которые вы встретите чаще всего -- это Draft-07 и Draft 2020-12.
Ключевые различия
| Функция | Draft-07 | Draft 2020-12 |
|---|---|---|
| prefixItems | Недоступно | Заменяет валидацию кортежей |
| $dynamicRef | Недоступно | Новое -- динамические ссылки на схемы |
| unevaluatedProperties | Недоступно | Решает проблему additionalProperties + allOf |
| Поддержка библиотек | Отличная | Хорошая и растущая |
Какую версию выбрать?
Выбирайте Draft-07, если ваша экосистема уже его использует или вам нужна максимальная совместимость.
Выбирайте Draft 2020-12, если начинаете новый проект без унаследованных ограничений.
Итог
Для большинства новых проектов в 2026 году Draft 2020-12 -- лучший выбор по умолчанию.
Как использовать наш генератор JSON Schema
Наш бесплатный генератор JSON Schema принимает любой JSON-payload и автоматически создаёт валидную схему. Всё работает в вашем браузере.
Пошаговое руководство
- Откройте инструмент Генератор JSON Schema.
- Вставьте ваш JSON в область ввода.
- Нажмите Сгенерировать, и инструмент проанализирует каждое поле, определит типы и обнаружит форматы.
- Проверьте результат -- сгенерированная схема появится в панели вывода.
- Переключитесь на вкладку Валидация, чтобы протестировать схему на новых JSON-payload.
- Скопируйте схему одним кликом и интегрируйте в свой проект.
Примечание о конфиденциальности
Наш генератор JSON Schema работает на 100% в вашем браузере. Ваши данные JSON, сгенерированные схемы и результаты валидации никогда не покидают ваше устройство.
Сгенерируйте JSON Schema мгновенно
Вставьте любой JSON-payload и получите готовую к использованию схему с выводом типов, обязательными полями и обнаружением форматов -- 100% в вашем браузере.