JSON Schema Draft 7

JSON Schema Draft 7 — это спецификация (черновик) стандарта описания и валидации структуры данных в формате JSON (JavaScript Object Notation). Она является частью серии черновиков (Draft), разрабатываемых сообществом под эгидой IETF (Internet Engineering Task Force) и предшествует финальному выпуску стандарта JSON Schema 2020-12. Draft 7, опубликованный в 2018 году, закрепил ряд ключевых возможностей, ставших основой для многих последующих реализаций, и до сих пор широко используется в промышленной разработке и документации API.

История и контекст

Разработка JSON Schema началась в 2007 году как неформальный проект для решения проблемы отсутствия единого способа описания и проверки JSON-данных. Первые черновики (Draft 0–3) были экспериментальными. Draft 4 (2013) стал первым относительно стабильным и широко внедрённым черновиком. Draft 6 (2017) ввёл ключевые слова для более гибкой валидации, такие как const и contains. Draft 7 (2018) стал логическим продолжением, добавив несколько новых ключевых слов и улучшив механизмы ссылок ($ref). После Draft 7 последовал Draft 8 (2019), который был переименован в JSON Schema 2020-12 — первый официальный стандарт, опубликованный как RFC (Request for Comments). Несмотря на это, Draft 7 остаётся одним из самых популярных и поддерживаемых черновиков, особенно в экосистемах языков программирования, где реализованы валидаторы, ориентированные на эту версию.

Основные возможности и ключевые слова

JSON Schema Draft 7 определяет структуру, типы данных, ограничения и взаимосвязи между элементами JSON-документа. Схема сама является JSON-файлом, что делает её самодокументируемой и легко обрабатываемой программно.

Типы данных и их валидация

Схема поддерживает шесть основных типов JSON: string, number, integer, boolean, array, object и null. Для каждого типа определены специфические ключевые слова:

• Для строк (string): minLength, maxLength, pattern (регулярное выражение), format (предопределённые форматы, такие как date-time, email, uri, ipv4, ipv6 и др.).
• Для чисел (number) и целых (integer): minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.
• Для массивов (array): minItems, maxItems, uniqueItems, items (схема для всех элементов), additionalItems (для массивов с кортежной структурой), contains (хотя бы один элемент соответствует схеме).
• Для объектов (object): properties (схемы для отдельных свойств), additionalProperties (схема для свойств, не указанных в properties), required (список обязательных свойств), minProperties, maxProperties, propertyNames (схема для имён свойств), dependencies (условная зависимость свойств).

Условная валидация и ссылки

Одним из ключевых нововведений Draft 7 стало ключевое слово if, then, else, позволяющее реализовать условную валидацию. Например, если свойство type равно "object", то должны быть выполнены дополнительные требования. Это заменило более сложные и менее читаемые конструкции, использовавшиеся в Draft 4.

Ключевое слово $ref обеспечивает механизм ссылок на другие части схемы или внешние схемы. В Draft 7 $ref может указывать на фрагмент внутри текущего документа (например, #/definitions/address) или на внешний URL. Важно, что в Draft 7 $ref не допускает параллельного использования других ключевых слов в том же объекте — это ограничение было снято в более поздних версиях.

Дополнительные ключевые слова

• definitions (или $defs в более поздних версиях) — контейнер для повторно используемых под-схем.
• examples — массив примеров значений, соответствующих схеме (не влияет на валидацию).
• readOnly и writeOnly — метаданные для описания доступности свойств в API.
• contentMediaType и contentEncoding — для описания встроенных медиа-данных (например, base64-encoded изображения).

Пример схемы на JSON Schema Draft 7

``json { "$schema": "http://json-schema.org/draft-07/schema#";, "title": "Пользователь", "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 }, "address": { "$ref": "#/definitions/address" } }, "required": ["id", "name", "email"], "if": { "properties": { "age": { "minimum": 18 } } }, "then": { "properties": { "isAdult": { "type": "boolean" } } }, "definitions": { "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string", "pattern": "^[0-9]{5}$" } }, "required": ["street", "city"] } } } ``

В этом примере схема описывает объект с обязательными полями id, name, email, а также необязательными age и address. С помощью if/then добавляется свойство isAdult, если возраст не менее 18. Ссылка $ref подключает определение адреса.

Применение

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

• Валидация данных: Проверка входящих JSON-запросов в API (например, в RESTful сервисах) на соответствие ожидаемой структуре. Многие веб-фреймворки (например, FastAPI, Spring Boot) интегрируют валидаторы на основе JSON Schema.
• Генерация документации: Инструменты вроде Swagger/OpenAPI используют JSON Schema для описания параметров запросов и ответов. OpenAPI 3.0 базируется на JSON Schema Draft 7 с некоторыми расширениями.
• Генерация кода: На основе схемы можно автоматически создавать классы моделей данных на различных языках программирования (Java, C#, Python, TypeScript).
• Тестирование: Схемы используются для проверки корректности тестовых данных и ответов от сервисов.
• Конфигурационные файлы: JSON Schema применяется для описания и валидации конфигураций в формате JSON (например, в Kubernetes, Docker Compose).

Реализации и поддержка

Существует множество библиотек, реализующих валидацию по JSON Schema Draft 7 на разных языках программирования. Наиболее известные:

• JavaScript: ajv (самый популярный), jsonschema.
• Python: jsonschema (с поддержкой Draft 7), fastjsonschema.
• Java: everit-json-schema, networknt/json-schema-validator.
• C#: Newtonsoft.Json.Schema (с поддержкой Draft 7), JsonSchema.Net.
• Go: gojsonschema, jsonschema.
• Ruby: json-schema.

Большинство современных валидаторов поддерживают Draft 7, хотя некоторые могут иметь неполную реализацию отдельных ключевых слов (например, format может быть реализован частично).

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

Несмотря на широкое распространение, JSON Schema Draft 7 имеет ряд недостатков, которые были частично устранены в более поздних версиях:

• Отсутствие поддержки $id в корне схемы: В Draft 7 использование $id для задания базового URI схемы может приводить к конфликтам при разрешении ссылок. Эта проблема решена в Draft 8.
• Ограничение на $ref: Как упоминалось, $ref не может быть использован вместе с другими ключевыми словами в одном объекте. Это вынуждало разработчиков создавать дополнительные обёртки.
• Сложность условной валидации: Хотя if/then/else улучшили ситуацию, для сложных бизнес-правил часто требуется комбинация нескольких ключевых слов, что делает схему громоздкой.
• Отсутствие поддержки перечисления с проверкой типов: Ключевое слово enum проверяет только равенство, но не тип. Например, "1" и 1 считаются разными значениями, но это может быть неочевидно.
• Производительность: Валидация сложных схем с большим количеством ссылок и условных конструкций может быть ресурсоёмкой.

Сравнение с более поздними версиями

JSON Schema 2020-12 (Draft 8) внёс несколько важных изменений по сравнению с Draft 7:

• $defs вместо definitions: Новое ключевое слово для под-схем.
• Разрешение $ref с другими ключевыми словами: Теперь можно писать { "$ref": "#/defs/foo", "description": "..." }.
• Улучшенная поддержка $id и $anchor: Более гибкое управление URI.
• Новые ключевые слова: unevaluatedProperties, unevaluatedItems, prefixItems (для кортежей), dependentRequired и dependentSchemas (замена dependencies).
• Удаление format из обязательной валидации: В Draft 7 format мог быть как обязательным, так и необязательным. В 2020-12 он стал полностью необязательным, если не указано иное.

Несмотря на эти улучшения, многие проекты остаются на Draft 7 из-за стабильности, широкой поддержки и обратной совместимости.

Источники

• IETF Internet-Draft: JSON Schema Validation: A Vocabulary for Structural Validation of JSON (draft-handrews-json-schema-validation-01, 2018).
• IETF Internet-Draft: JSON Schema: A Media Type for Describing JSON Documents (draft-handrews-json-schema-01, 2018).
• Официальная документация JSON Schema (json-schema.org).
• Репозиторий спецификации JSON Schema на GitHub (json-schema-org/json-schema-spec).
• Документация библиотеки ajv (npmjs.com/package/ajv).
• Статья «JSON Schema: A Practical Guide» на сайте DigitalOcean (2020).