JSON Schema

JSON Schema — это декларативный язык описания структуры и типов данных в формате JSON (JavaScript Object Notation). Он позволяет задавать правила валидации для JSON-документов: какие поля обязательны, какие типы данных допустимы, диапазоны чисел, паттерны строк, ограничения на размер массивов и вложенные структуры. JSON Schema широко применяется для автоматической проверки корректности данных в веб-API, конфигурационных файлах, системах обмена данными и документирования форматов.

История и развитие

Идея формального описания JSON-данных возникла вскоре после распространения самого JSON как альтернативы XML. Первая черновая спецификация JSON Schema была предложена Крисом Таунсендом (Chris Townsend) и Фрэнсисом Шаном (Francis Shan) в 2007 году. В 2009 году началась работа над проектом IETF (Internet Engineering Task Force), который стандартизировал версию JSON Schema Draft 3. В 2013 году вышла Draft 4, ставшая наиболее широко используемой реализацией. Последующие версии (Draft 5, Draft 6, Draft 7) добавляли новые ключевые слова и уточняли поведение валидаторов. В 2019 году был опубликован стандарт JSON Schema 2019-09 (Draft 8), а в 2020 году — JSON Schema 2020-12. На 2025 год актуальной является версия 2020-12, хотя многие проекты продолжают использовать Draft 4 или Draft 7.

Основные понятия

Схема как JSON-документ

JSON Schema сама по себе является JSON-объектом, который содержит ключевые слова (keywords), определяющие правила валидации. Схема может быть встроена прямо в приложение или передаваться отдельно (например, в HTTP-заголовке Content-Type при использовании медиатипа application/schema+json).

Валидация

Процесс проверки JSON-документа на соответствие схеме называется валидацией. Валидатор (программа или библиотека) анализирует экземпляр JSON и сообщает, соответствует ли он всем заданным ограничениям. Если документ не проходит проверку, валидатор возвращает список ошибок с указанием пути к проблемному полю и описанием нарушения.

Ключевые слова валидации

Тип данных

Ключевое слово type задаёт ожидаемый тип JSON-значения. Допустимые значения: string, number, integer, boolean, array, object, null. Можно указать несколько типов через массив, например ["string", "null"].

Строки

Для строковых полей используются ключевые слова:

• minLength и maxLength — минимальная и максимальная длина строки в символах.
• pattern — регулярное выражение (в стиле ECMA-262), которому должна соответствовать строка.
• format — именованный формат (например, "email", "uri", "date-time", "ipv4"). Форматы не являются обязательными для проверки, но многие валидаторы их поддерживают.

Числа

Для чисел (типы number и integer) применяются:

• minimum и maximum — границы значений.
• exclusiveMinimum и exclusiveMaximum — строгие границы (значение не может равняться границе).
• multipleOf — число должно быть кратно указанному значению.

Массивы

Для массивов доступны:

• minItems и maxItems — минимальное и максимальное количество элементов.
• uniqueItems — булево значение, требующее уникальности элементов.
• items — схема для всех элементов массива (если задан объект) или список схем для поэлементной валидации (если задан массив).
• prefixItems (в версии 2020-12) — список схем для первых элементов массива (аналог items-массива в старых версиях).
• contains — схема, которой должен соответствовать хотя бы один элемент массива.

Объекты

Для объектов используются:

• properties — объект, где ключи — имена полей, а значения — их схемы.
• additionalProperties — схема для любых полей, не перечисленных в properties или patternProperties. Если установлено false, дополнительные поля запрещены.
• required — массив строк, перечисляющий обязательные поля.
• minProperties и maxProperties — минимальное и максимальное количество полей.
• patternProperties — объект, где ключи — регулярные выражения, а значения — схемы для полей, чьи имена соответствуют этим выражениям.
• dependentRequired — если поле присутствует, то должны присутствовать и указанные зависимые поля.
• dependentSchemas — если поле присутствует, то к документу применяется дополнительная схема.

Логические комбинации

JSON Schema поддерживает булеву логику для комбинирования условий:

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

Ссылки и рекурсия

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

Аннотации и метаданные

Схема может содержать не только правила валидации, но и метаданные:

• title — краткое название схемы.
• description — описание.
• default — значение по умолчанию.
• examples — массив примеров.
• readOnly и writeOnly — булевы флаги для указания, что поле доступно только для чтения или только для записи (полезно для API).

Версии и совместимость

Основные версии JSON Schema:

• Draft 3 (2009) — первая стабильная версия, ныне устаревшая.
• Draft 4 (2013) — наиболее распространённая версия, поддерживается большинством библиотек.
• Draft 6 (2016) — добавил const, contains и propertyNames.
• Draft 7 (2018) — добавил if/then/else для условной валидации.
• 2019-09 (Draft 8) — ввёл $defs, dependentRequired, dependentSchemas, unevaluatedProperties, unevaluatedItems.
• 2020-12 — актуальная версия, изменил поведение $ref, добавил prefixItems, уточнил обработку format.

Совместимость между версиями неполная: схемы Draft 4 не всегда корректно обрабатываются валидаторами версии 2020-12 и наоборот. Рекомендуется указывать версию схемы с помощью ключевого слова $schema (например, "$schema": "https://json-schema.org/draft/2020-12/schema"`).