JSON Schema — это способ описать, какой должна быть структура JSON-документа, с помощью другого JSON-документа. Вместо того чтобы проверять данные вручную условиями в коде, можно декларативно описать ожидаемые типы, обязательные поля и ограничения значений, а затем проверять данные автоматически.
Основные ключевые слова draft-07
type— ожидаемый тип значения (object, string, number, array и т.д.).required— список полей объекта, которые обязательно должны присутствовать.properties— описание схемы для каждого поля объекта отдельно.enum— ограничение значения конкретным перечнем вариантов.pattern— проверка строки регулярным выражением, например для формата ИНН или телефона.
Пример: pattern для российского ИНН
ИНН физического лица — это 12 цифр, юридического лица — 10 цифр. Схема для поля контрагента в API может выглядеть так: "inn": {"type": "string", "pattern": "^\\d{10}(\\d{2})?$"} — строка ровно из 10 или 12 цифр. Это не проверяет контрольную сумму ИНН (для неё нужен отдельный алгоритм), но сразу отсекает опечатки вроде лишнего пробела, буквы вместо цифры или неверной длины — то, с чем регулярно сталкивается любой бэкенд, принимающий реквизиты контрагентов через форму.
Чем это отличается от валидации синтаксиса
Обычная валидация JSON проверяет лишь, что текст синтаксически корректен — правильные скобки, кавычки, запятые. JSON Schema проверяет значительно больше: есть ли в объекте обязательное поле email, является ли значение age числом, а не строкой, входит ли status в разрешённый перечень значений.
Зачем это нужно
- Проверить, что ответ стороннего API соответствует задокументированному контракту.
- Валидировать конфигурационные файлы перед деплоем, чтобы поймать ошибку раньше.
- Задокументировать ожидаемую структуру данных в формате, который сразу можно автоматически проверить.
additionalProperties: можно ли добавлять лишние поля
По умолчанию JSON Schema разрешает в объекте любые поля сверх описанных в properties — required и properties лишь устанавливают минимум, а не исчерпывающий перечень. Если нужно запретить неизвестные поля, нужно явно добавить "additionalProperties": false — без этого флага схема остаётся «открытой».