JSON Schema 2020-12

JSON Schema 2020-12 — это версия спецификации JSON Schema, опубликованная в 2020 году (формально — как серия релизов, включающих черновики 2020-12, 2021-12 и окончательную стабильную версию 2020-12 в 2022 году). Она представляет собой набор правил и ключевых слов для описания структуры, типов данных, ограничений и взаимосвязей в документах формата JSON (JavaScript Object Notation). JSON Schema 2020-12 является эволюционным развитием предыдущих версий (в частности, Draft-07 и Draft 2019-09) и направлена на стандартизацию валидации, документирования и автоматической обработки JSON-данных.

История

Разработка JSON Schema началась в 2009–2010 годах как неформальное сообщество разработчиков, столкнувшихся с необходимостью формального описания структуры JSON. Первые черновики (Draft-01 — Draft-04) заложили базовые концепции: типы (string, number, object, array), ключевые слова properties, required, additionalProperties, enum и др. Версия Draft-07 (2018) стала широко распространённой и де-факто стандартом для многих инструментов.

В 2019 году вышла версия Draft 2019-09, которая ввела значительные изменения: поддержку рекурсивных схем, ключевое слово $recursiveAnchor, а также новую систему идентификации $id. Однако сообщество столкнулось с проблемами совместимости и неоднозначностями. В ответ на это была разработана JSON Schema 2020-12, которая:

• Устранила неоднозначности Draft 2019-09.
• Ввела ключевое слово $dynamicRef для более гибкой обработки рекурсивных и циклических ссылок.
• Уточнила поведение $anchor и $recursiveAnchor.
• Стандартизировала формат URI-фрагментов для схем.
• Определила механизмы расширения через $vocabulary.

Финальная спецификация была опубликована в январе 2022 года как RFC (Request for Comments) в рамках IETF (Internet Engineering Task Force) — документ RFC 8927.

Основные концепции

JSON Schema 2020-12 описывает JSON-документ (схему), который сам является валидным JSON-объектом. Схема содержит ключевые слова (keywords), каждое из которых задаёт определённое ограничение или правило. Основные категории ключевых слов:

• Типы данных: type (string, number, integer, object, array, boolean, null).
• Структурные ограничения: properties, additionalProperties, required, items, prefixItems, contains, unevaluatedProperties, unevaluatedItems.
• Числовые ограничения: minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.
• Строковые ограничения: minLength, maxLength, pattern (регулярное выражение), format (например, date-time, email, uri).
• Массивы: minItems, maxItems, uniqueItems, contains, prefixItems (для кортежей).
• Логические комбинаторы: allOf, anyOf, oneOf, not.
• Ссылки и рекурсия: $ref, $defs, $dynamicRef, $anchor, $recursiveAnchor.

Ключевое слово $id

Каждая схема может иметь уникальный идентификатор в виде URI, задаваемый ключевым словом $id. Этот идентификатор используется для разрешения относительных ссылок ($ref) и для импорта схем из других файлов. В версии 2020-12 идентификаторы могут быть абсолютными или относительными, что позволяет создавать модульные иерархические схемы.

Ключевое слово $dynamicRef

Одно из ключевых нововведений — $dynamicRef и связанное с ним $dynamicAnchor. Они предназначены для обработки рекурсивных и полиморфных структур, когда одна и та же схема может ссылаться на себя в разных контекстах. В отличие от $ref, который разрешается статически (по URI), $dynamicRef разрешается динамически, в зависимости от текущего контекста валидации. Это позволяет, например, описывать списки, содержащие элементы разного типа, или рекурсивные деревья с наследованием.

Ключевое слово $vocabulary

$vocabulary — механизм расширения схемы. Позволяет указать, какие дополнительные ключевые слова (не входящие в базовую спецификацию) могут использоваться в данной схеме, и задаёт их семантику. Это открывает путь для создания отраслевых или корпоративных расширений без нарушения совместимости.

Ключевое слово unevaluatedProperties / unevaluatedItems

Эти ключевые слова решают проблему «непроверенных» свойств или элементов после обработки всех allOf, anyOf и других комбинаторов. unevaluatedProperties проверяет свойства, которые не были явно обработаны ни одним из ключевых слов (например, в properties или additionalProperties). Аналогично unevaluatedItems — для элементов массива.

Отличия от предыдущих версий

Применение

JSON Schema 2020-12 используется в следующих областях:

• Валидация данных: автоматическая проверка JSON-документов на соответствие схеме (например, в API-шлюзах, формах, конфигурационных файлах).
• Генерация документации: из схемы можно автоматически создавать описания API (например, OpenAPI 3.1, который базируется на JSON Schema 2020-12).
• Генерация кода: некоторые инструменты (например, quicktype, json-schema-to-typescript) генерируют типы данных на TypeScript, Java, C# и других языках на основе схемы.
• Тестирование: схемы используются для автоматической генерации тестовых данных и проверки корректности ответов API.
• Конфигурационные файлы: многие системы (например, Kubernetes, Ansible, Helm) используют JSON Schema для валидации YAML/JSON-конфигураций.

Инструменты

Существует множество реализаций валидаторов JSON Schema 2020-12 на разных языках программирования:

• JavaScript/Node.js: ajv, jsonschema, @cfworker/json-schema.
• Python: jsonschema (с поддержкой 2020-12 в версии 4.0+), python-jsonschema-objects.
• Java: everit-json-schema, networknt/json-schema-validator.
• Go: gojsonschema, jsonschema (github.com/santhosh-tekuri/jsonschema).
• .NET: Newtonsoft.Json.Schema, JsonSchema.Net.
• Ruby: json_schemer.

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

• Сложность: версия 2020-12 значительно сложнее предыдущих, что затрудняет её изучение и реализацию.
• Производительность: динамическое разрешение ссылок ($dynamicRef) может снижать скорость валидации на больших схемах.
• Неполная поддержка: не все инструменты и библиотеки полностью реализуют спецификацию 2020-12; некоторые ограничиваются подмножеством ключевых слов.
• Отсутствие строгой типизации: JSON Schema не поддерживает типы, отличные от примитивов JSON (например, даты, бинарные данные, перечисления с пользовательскими метками), хотя format частично решает эту проблему.

Пример схемы

Ниже приведён пример простой схемы на JSON Schema 2020-12, описывающей объект «пользователь»:

``json { "$schema": "https://json-schema.org/draft/2020-12/schema";, "$id": "https://example.com/schemas/user.json";, "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "age": { "type": "integer", "minimum": 0, "maximum": 150 }, "roles": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } }, "required": ["name", "email"], "additionalProperties": false } ``

Эта схема требует, чтобы JSON-документ был объектом с обязательными полями name (строка не менее 1 символа) и email (строка, соответствующая формату email), необязательным age (целое число от 0 до 150) и необязательным массивом roles с уникальными строками. Любые дополнительные свойства запрещены (additionalProperties: false).

Источники

• RFC 8927 — JSON Schema: A Media Type for Describing JSON Documents (IETF, 2022).
• JSON Schema Specification 2020-12 (json-schema.org, 2022).
• Understanding JSON Schema 2020-12 (UnderstandingJSONSchema.com, 2023).
• JSON Schema Validation: A Practical Guide (O'Reilly Media, 2021).
• Документация библиотеки ajv (ajv.js.org, версия 8.x).