Как применять JSON Schema для проверки данных

JSON Schema — декларативный язык описания структуры и ограничений JSON-документа. Он помогает проверить, есть ли обязательные поля, соответствуют ли значения типам и диапазонам, разрешены ли дополнительные свойства. Корректный синтаксис JSON сам по себе этих гарантий не даёт.

Используйте схему, когда один документ проходит через API, импорт, интерфейс и фоновые обработчики либо когда состав типов расширяется независимо от выпуска приложения. Зафиксируйте диалект, настройки валидаторов, правила изменений и примеры допустимых и ошибочных данных. Проверку в браузере дополните серверной.

Результат работы — согласованный контракт и воспроизводимые проверки на границах системы. Схема не заменяет авторизацию, бизнес-правила и модель хранения. Ниже разберём учебный пример, границы применения и порядок внедрения для аналитика, архитектора и инженера.

Рассмотрим условную настройку правила оповещения. Поле enabled включает правило, threshold задаёт целочисленный порог от 1 до 100. Пример учебный: он показывает механизм проверки, а не устройство конкретного проекта.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "enabled",
    "threshold"
  ],
  "properties": {
    "enabled": {
      "type": "boolean",
      "title": "Включено",
      "default": true
    },
    "threshold": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "title": "Порог"
    }
  }
}

Объект {"enabled": true, "threshold": 20} соответствует этой схеме. Объект {"enabled": "иногда", "threshold": -500, "unexpectedField": {}} является синтаксически корректным JSON, но нарушает тип, диапазон и правило дополнительных полей. Какие ошибки вернутся одновременно, зависит от настроек валидатора.

Отсутствие, null и значение по умолчанию

Отсутствующее свойство, JSON null и пустая строка — разные состояния. Для enabled значение null в примере недопустимо, потому что разрешён только boolean. Если поле должно принимать null, это отражают явно, например типом ["string", "null"]. Затем отдельно определяют, обязательно ли само присутствие поля.

default — аннотация: стандартная проверка не обязана вставлять её в документ. Поэтому отсутствие обязательного enabled здесь остаётся ошибкой, хотя в схеме записано default: true. Интерфейс может использовать это значение при создании формы; сохранение результата требует отдельного решения приложения. Это различие объясняет руководство JSON Schema по аннотациям ↗.

Форматы и составные схемы

format: date-time описывает строку даты и времени, но обязательность проверки зависит от словаря и конфигурации валидатора. В стандартном диалекте Draft 2020-12 поддержка format как утверждения о валидности не обязательна. Проверяйте конкретный инструмент и настройки, а не только наличие ключевого слова. Нормативное различие приведено в JSON Schema Validation ↗.

allOf требует выполнения всех вложенных схем, anyOf — хотя бы одной, oneOf — ровно одной. Это применение ограничений, а не наследование классов с переопределением полей. При сочетании закрытых объектов и составных схем учитывайте область действия additionalProperties; для некоторых композиций подходит unevaluatedProperties, если выбранный диалект и инструменты его поддерживают. Подробнее — комбинирование схем ↗ и ограничения объектов ↗.

Проблема появляется, когда несколько компонентов по-разному понимают один документ. Форма допускает строку, API ожидает число, импорт добавляет неизвестное поле, а обработчик использует старое название. Машиночитаемая схема уменьшает повторное описание правил, если потребители действительно используют согласованную версию и одинаково трактуют поддерживаемые возможности.

TypeScript удаляет сведения о типах при компиляции: типизированная переменная не доказывает, что внешний JSON соответствует ожиданиям. Это свойство показано в документации TypeScript ↗. Схемы и статические типы можно согласовывать генерацией артефактов и контрактными тестами; важно проверять ограничения, которые генератор не смог выразить.

OpenAPI не следует объявлять недостаточным по определению. OpenAPI 3.1 ↗ поддерживает JSON Schema и ссылки на внешние схемы. Стабильный HTTP-контракт может ссылаться на общий артефакт. Отдельный реестр полезен, когда набор типов и их версии имеют самостоятельный жизненный цикл, но не каждый новый тип требует пересборки всех клиентов: это зависит от генерации и поведения потребителей.

При динамическом конверте type + data сервер должен по разрешённому типу выбрать точную схему содержимого. Произвольный URL схемы из запроса нельзя безусловно загружать. Неизвестный тип должен давать предусмотренную ошибку или ограниченный режим просмотра, а не обход проверки.

Если задача касается изменяемых характеристик объектов, сначала выберите модель динамических атрибутов. EAV описывает организацию значений, JSON Schema — ограничения JSON-документа. Они решают разные задачи и могут использоваться вместе.

Начните с одного документа и полного пути его обработки. Общая схема полезна только там, где известны границы ответственности: кто создаёт данные, кто выбирает версию контракта, кто отклоняет ошибку и кто объясняет её пользователю. Универсальный редактор всех возможных сущностей не нужен для первого шага.

1. Соберите входы и потребителей. Возьмите допустимые, неполные и ошибочные примеры, включая старые сохранённые документы. Аналитик фиксирует смысл, единицы, обязательность и неизвестные значения.
2. Выберите диалект и профиль. Архитектор указывает поддерживаемые keywords, форматы, ссылки и расширения. Небольшой проверенный профиль часто проще, чем обещание поддержки всего стандарта.
3. Проверьте саму схему. Выполните проверку метасхемой и компиляцию выбранным инструментом. Настройте поведение неизвестных ключевых слов; опечатка в ограничении не должна незаметно ослаблять контракт.
4. Подключите серверные границы. Проверьте API, импорт и обработку сообщений. Передайте понятные путь к полю и причину отказа; не возвращайте внутренние секреты и весь исходный документ без необходимости.
5. Согласуйте интерфейс и тесты. Запускайте один набор примеров во всех используемых валидаторах. Зафиксируйте, где применяются defaults и преобразования, и повторяйте проверки при обновлении библиотек.

Клиентская проверка ускоряет обратную связь, но запрос может прийти напрямую, из старого клиента или фонового процесса. Окончательную проверку выполняют на сервере. OWASP Input Validation Cheat Sheet ↗ рекомендует серверную валидацию и явное описание допустимого ввода.

Что может построить интерфейс

По схеме можно выбрать базовый элемент: boolean — переключатель, enum — список вариантов, массив — повторяемую группу. title и description помогают с подписями. Но стандарт не определяет расположение полей, удалённые справочники, права, доступность и полный сценарий работы пользователя.

Разделяйте контракт данных и настройки представления. Для сложного поля допустим заранее реализованный компонент, выбираемый по согласованному идентификатору. Расширение вроде x-formatter: duration является локальной договорённостью, а не стандартным поведением JSON Schema; строгий валидатор может потребовать его регистрации. Хранить произвольный JavaScript в схеме для форматирования опаснее и обычно избыточно.

Диалект стандарта и прикладная версия — разные вещи. $schema указывает, как читать схему, $id идентифицирует ресурс и задаёт основу разрешения ссылок. Ни одно из этих полей само по себе не назначает активную версию бизнес-контракта. Правила идентификации объясняет руководство по структуре схемы ↗.

Обновление проверяют в нужном направлении: сможет ли новый потребитель прочитать старые данные и сможет ли старый потребитель обработать новые. Расширение enum позволяет новому валидатору принять старые значения, но старый клиент может не знать добавленный вариант. Необязательное поле не нарушает старые документы под новой схемой, однако новый документ с этим полем может не пройти старую закрытую схему.

Смена секунд на миллисекунды способна оставить тот же числовой тип и диапазон. Структурная проверка не докажет сохранение смысла. Для изменения единиц, кодов и значения отсутствия нужны отдельные миграционные правила и тесты поведения. Порядок выпуска и проверки обоих направлений разобран в руководстве по Schema Registry и совместимости версий.

Defaults, преобразования и доверие

Некоторые инструменты умеют изменять данные при проверке. Например, Ajv ↗ предлагает дополнительные настройки вставки defaults, удаления свойств и преобразования типов. Это расширенное поведение реализации: включайте его явно и проверяйте последствия для повторной обработки, аудита и разных языков программирования.

Недоверенные схемы могут содержать дорогие регулярные выражения, рекурсию и внешние ссылки. Ограничивайте размер документа и схемы, глубину, разрешение ссылок и ресурсы проверки с учётом инструмента. Схемы лучше компилировать и проверять при публикации версии; выполнение проверки по непроверенной схеме из каждого запроса создаёт лишний риск. Нужные ограничения описаны в разделе безопасности спецификации JSON Schema Core ↗.

Успешная валидация не доказывает право на операцию, существование объекта или допустимость перехода статуса. Эти проверки выполняются в прикладном сервисе. Понятный контракт ошибок должен различать неверную структуру, неизвестную версию, нарушение бизнес-правила и отказ в доступе.

Типовые ошибки — считать properties обязательностью, ожидать автоматической подстановки default, доверять одной frontend-проверке и включать преобразование типов только в одном из потребителей. Ещё одна ошибка — распространять локальный UI keyword на сторонние инструменты без согласованного профиля.

На выходе нужны версия схемы, описание значений и единиц, профиль валидаторов, позитивные и негативные примеры, правила ошибок и план изменения сохранённых данных. Добавьте владельца контракта и перечень его потребителей. Это небольшой согласованный пакет, по которому команда может реализовать и проверить один путь обработки.

Для JSON-полей в PostgreSQL отдельно оцените хранение и индексацию JSONB. Схема проверяет документ, а решение о колонках и индексах опирается на запросы. Для передачи между системами включите версию и правила ошибок в документацию интеграций и API.