Открыть сервис
Главная → Блог → JSON Schema

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"`).

Применение

Валидация данных в веб-API

Многие REST API используют JSON Schema для автоматической проверки входящих запросов и ответов. Например, спецификация OpenAPI (Swagger) включает JSON Schema как часть описания параметров и тел запросов. Фреймворки (FastAPI, Flask, Express) интегрируют валидацию на основе схем.

Конфигурационные файлы

Инструменты и приложения, использующие JSON-конфигурацию (например, ESLint, Prettier, VS Code), предоставляют JSON Schema для автодополнения и проверки в редакторах кода.

Генерация документации

По схеме можно автоматически сгенерировать человекочитаемую документацию формата данных (например, с помощью инструментов типа json-schema-to-markdown).

Генерация кода

Существуют инструменты, которые по JSON Schema генерируют классы, структуры или типы на языках программирования (TypeScript, Python, Java, C#). Это ускоряет разработку и уменьшает количество ошибок при работе со сложными структурами.

Тестирование и фаззинг

Схемы используются для генерации тестовых данных (например, библиотека json-schema-faker) или для проверки, что система корректно обрабатывает все допустимые варианты данных.

Пример схемы

Ниже приведён пример простой JSON Schema для описания пользователя:

``json { "$schema": "https://json-schema.org/draft/2020-12/schema";, "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 }, "roles": { "type": "array", "items": { "type": "string", "enum": ["admin", "user", "moderator"] }, "uniqueItems": true } }, "required": ["id", "name", "email"] } ``

Данная схема требует, чтобы JSON-документ был объектом с обязательными полями id, name и email. Поле id должно быть целым числом не меньше 1, name — непустой строкой до 100 символов, email — строкой в формате email, age — целым числом от 0 до 150, roles — массивом уникальных строк, каждая из которых может быть только admin, user или moderator.

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

Основные недостатки JSON Schema:

  • Сложность для больших схем — при описании глубоко вложенных структур с множеством условных зависимостей схема становится трудночитаемой.
  • Отсутствие строгой типизации — JSON Schema не поддерживает пользовательские типы данных (например, UUID, дата без времени) без использования format, который не является обязательным для валидаторов.
  • Производительность — валидация сложных схем с рекурсивными ссылками и множеством комбинаций (allOf, anyOf) может быть медленной для больших документов.
  • Фрагментация версий — из-за неполной обратной совместимости проекты часто застревают на старых версиях, что затрудняет обновление экосистемы.

Инструменты

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

  • JavaScript/TypeScript: Ajv (самый быстрый валидатор), jsonschema, tv4.
  • Python: jsonschema (реализация Draft 4–2020-12), fastjsonschema.
  • Java: everit-json-schema, networknt/json-schema-validator.
  • Go: gojsonschema, jsonschema.
  • C#: Newtonsoft.Json.Schema, JsonSchema.Net.
  • Ruby: json-schema.

Онлайн-редакторы и валидаторы (например, jsonschemavalidator.net, json-schema.org/validator) позволяют тестировать схемы без установки ПО.

Источники

  • JSON Schema Specification (IETF Internet-Draft, 2020-12)
  • JSON Schema: Understanding JSON Schema (справочное руководство)
  • OpenAPI Specification (версии 3.0 и 3.1)
  • Документация библиотеки Ajv
  • Статья «JSON Schema» в английской Википедии

BFOmetr — база данных и аналитика по компаниям России.

На главную BFOmetr →

Похожие материалы