Валидация JSON Schema: полное руководство по драфтам и правилам

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

• 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) — крупная реструктуризация. Введены $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'. Это часто выявляет неправильные форматы адресов электронной почты, телефонных номеров или пользовательских идентификаторов, не следующих ожидаемому шаблону.
• Ошибка разрешения $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 для сохранения читаемости схемы. Глубина вложенности не ограничена — валидатор рекурсивно проверяет каждый уровень.