JSON Schema Draft 4

Ключевые слова для валидации значений

Эти ключевые слова применяются в зависимости от типа данных, указанного в type (или без него, если тип не указан, они проверяются для всех типов, где это имеет смысл).

• Для строк (string):
• minLength / maxLength — минимальная/максимальная длина строки.
• pattern — регулярное выражение (ECMAScript), которому должна соответствовать строка.
• format — формат строки (например, date-time, email, hostname, ipv4, uri). В Draft 4 форматы не являются обязательными для валидации (это рекомендация), но многие реализации их поддерживают.

• Для чисел (number, integer):
• minimum / maximum — минимальное/максимальное значение.
• exclusiveMinimum / exclusiveMaximum — в Draft 4 эти ключевые слова могут быть как логическими (true/false), так и числами. Если логическое true, то значение должно быть строго больше minimum (или строго меньше maximum). Если число — то оно само является границей (это поведение было унифицировано в более поздних версиях).
• multipleOf — число, на которое значение должно делиться без остатка.

• Для массивов (array):
• minItems / maxItems — минимальное/максимальное количество элементов.
• uniqueItems — логическое значение: если true, все элементы массива должны быть уникальны (сравнение по значению, а не по ссылке).

• Для объектов (object):
• minProperties / maxProperties — минимальное/максимальное количество свойств.
• dependencies — объект, где ключ — свойство, а значение — массив свойств или схема. Если ключ присутствует, то должны присутствовать и все свойства из массива, или объект должен соответствовать схеме.

• Для всех типов:
• enum — массив допустимых значений.
• allOf, anyOf, oneOf — логические комбинации схем (см. ниже).
• not — схема, которой значение не должно соответствовать.

Логические комбинаторы

JSON Schema Draft 4 поддерживает логические операторы для комбинирования схем:

• allOf — массив схем: значение должно соответствовать всем схемам.
• anyOf — массив схем: значение должно соответствовать хотя бы одной схеме.
• oneOf — массив схем: значение должно соответствовать ровно одной схеме.
• not — схема: значение не должно соответствовать данной схеме.

Ссылки ($ref)

Ключевое слово $ref позволяет ссылаться на другую схему (или её часть) по URI. В Draft 4 ссылки разрешаются путём подстановки целевой схемы на место ссылки. Это позволяет создавать модульные и переиспользуемые схемы.

Пример схемы

Ниже приведён пример схемы JSON Schema Draft 4 для описания объекта «пользователь»:

``json { "$schema": "http://json-schema.org/draft-04/schema#";, "title": "Пользователь", "description": "Схема для объекта пользователя", "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email" }, "age": { "type": "integer", "minimum": 0, "maximum": 150 }, "isActive": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string", "enum": ["admin", "user", "moderator"] }, "uniqueItems": true, "minItems": 1 } }, "required": ["id", "name", "email"] } ``

Данная схема описывает объект, который:

• Должен быть объектом (type: "object").
• Иметь обязательные свойства id, name, email.
• Свойство id — целое число не менее 1.
• Свойство name — строка длиной от 1 до 100 символов.
• Свойство email — строка, соответствующая формату email.
• Свойство age — целое число от 0 до 150 (необязательное).
• Свойство isActive — логическое значение (необязательное).
• Свойство roles — массив строк, где каждый элемент — одно из трёх значений, все элементы уникальны, минимум один элемент (необязательное).

Применение

JSON Schema Draft 4 широко используется в следующих областях:

• Валидация данных — проверка входящих JSON-данных в API, конфигурационных файлов, сообщений в системах обмена данными.
• Документирование API — в спецификациях OpenAPI (Swagger) версий 2.0 и 3.0 для описания тел запросов и ответов.
• Генерация кода — автоматическое создание классов, структур данных и парсеров на основе схем.
• Тестирование — генерация тестовых данных, соответствующих схеме.
• Обмен данными — обеспечение согласованности структуры данных между различными системами и сервисами.

Критика и ограничения

Несмотря на популярность, JSON Schema Draft 4 имеет ряд недостатков, которые были частично исправлены в последующих версиях:

• Неоднозначность exclusiveMinimum/exclusiveMaximum — в Draft 4 эти ключевые слова могут быть как логическими, так и числовыми, что приводит к путанице.
• Отсутствие поддержки условной валидации — нет ключевых слов if/then/else (появились в Draft 7).
• Сложность с additionalProperties — если properties не указан, additionalProperties не имеет эффекта, что может приводить к ошибкам.
• Ограниченная поддержка format — форматы не являются обязательными для валидации, поэтому разные реализации могут вести себя по-разному.
• Отсутствие поддержки const — ключевое слово для точного совпадения значения появилось в Draft 6.
• Проблемы с $ref — в Draft 4 ссылки разрешаются путём подстановки, что может нарушать логику комбинаторов (например, allOf с $ref).

Современное состояние

JSON Schema Draft 4 остаётся актуальным для многих устаревших проектов, но для новых разработок рекомендуется использовать более новые версии (Draft 7, 2019-09, 2020-12), которые исправляют многие недостатки и добавляют новые возможности. Тем не менее, значительная часть экосистемы (библиотеки, инструменты, документация) всё ещё ориентируется на Draft 4, что делает его важным для понимания истории и практики использования JSON Schema.

Источники

• IETF Internet-Draft: JSON Schema: core definitions and terminology (draft-fge-json-schema-validation-00, 2013)
• IETF Internet-Draft: JSON Schema: interactive and non-interactive validation (draft-fge-json-schema-validation-00, 2013)
• Официальный сайт JSON Schema (json-schema.org) — раздел «Understanding JSON Schema» (версия для Draft 4)
• Документация библиотеки Ajv (Another JSON Validator) — поддержка Draft 4
• Спецификация OpenAPI 3.0 — раздел о JSON Schema