Структура объекта ошибки

Валидационные ошибки, которые формирует Ajv, представляют собой структурированные объекты, содержащие информацию о том, какое правило JSON Schema было нарушено, где именно это произошло и какие данные стали причиной несоответствия. Каждая ошибка соответствует одному нарушению конкретного ограничения схемы.

Типичная структура объекта ошибки включает следующие ключевые поля:

  • instancePath
  • schemaPath
  • keyword
  • params
  • message
  • schema
  • parentSchema

Каждое поле выполняет строго определённую роль и позволяет точно локализовать проблему в проверяемых данных.

instancePath: путь к ошибочным данным

Поле instancePath содержит JSON Pointer-путь к элементу данных, который не прошёл проверку.

Пример:

instancePath: "/user/address/zip"

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

Особенности:

  • путь всегда начинается с корня объекта
  • используется формат JSON Pointer
  • пустая строка означает, что ошибка относится к корневому объекту

schemaPath: путь к правилу схемы

Поле schemaPath указывает на конкретное правило JSON Schema, которое было нарушено.

Пример:

schemaPath: "#/properties/user/properties/age/minimum"

Значение показывает, что ошибка связана с ограничением minimum для свойства age.

Функциональная роль:

  • позволяет связать ошибку с конкретным фрагментом схемы
  • полезно при сложных схемах с вложенными объектами и комбинированными правилами

keyword: тип нарушенного правила

Поле keyword указывает, какое именно правило JSON Schema вызвало ошибку.

Наиболее часто встречающиеся значения:

  • type — несоответствие типа данных
  • required — отсутствует обязательное поле
  • minimum / maximum — нарушение числовых ограничений
  • minLength / maxLength — нарушение ограничений строки
  • pattern — несоответствие регулярному выражению
  • additionalProperties — наличие лишних свойств
  • enum — значение не входит в допустимый набор

Это поле определяет семантику ошибки и позволяет группировать ошибки по типу нарушения.

params: параметры правила

Поле params содержит дополнительные данные, специфичные для конкретного keyword.

Примеры:

Для minimum:

params: { limit: 18 }

Для required:

params: { missingProperty: "email" }

Для type:

params: { type: "string" }

Назначение поля:

  • передаёт контекст нарушения
  • позволяет формировать точные сообщения об ошибке
  • зависит от конкретного правила схемы

message: текстовое описание ошибки

Поле message содержит человекочитаемое описание ошибки, сформированное Ajv.

Примеры:

  • "must be >= 18"
  • "must have required property 'email'"
  • "must be string"

Особенности:

  • генерируется автоматически
  • зависит от локализации и конфигурации Ajv
  • может быть переопределено через кастомные сообщения

schema: фрагмент схемы

Поле schema содержит значение схемы, которое участвовало в проверке.

Пример:

schema: 18

или

schema: { type: "string" }

Назначение:

  • показывает правило, которое было применено
  • полезно при отладке сложных схем
  • не всегда присутствует в зависимости от конфигурации

parentSchema: контекст схемы

Поле parentSchema содержит объект родительской схемы, в которой определено нарушенное правило.

Это позволяет:

  • понять контекст правила внутри структуры схемы
  • анализировать вложенные конструкции allOf, anyOf, oneOf
  • диагностировать сложные композиции схем

Структурирование ошибок в массиве

Ajv возвращает ошибки в виде массива объектов, где каждая ошибка независима:

errors: [
  {
    instancePath: "/age",
    schemaPath: "#/properties/age/minimum",
    keyword: "minimum",
    params: { limit: 18 },
    message: "must be >= 18"
  },
  {
    instancePath: "/email",
    schemaPath: "#/required",
    keyword: "required",
    params: { missingProperty: "email" },
    message: "must have required property 'email'"
  }
]

Каждый элемент массива описывает одно нарушение, даже если оно является частью более сложной валидации.

Особенности формирования ошибок

При работе Ajv учитывает ряд внутренних правил формирования объектов ошибок:

  • при использовании allErrors: true возвращаются все найденные нарушения, а не только первое
  • при использовании strict режима добавляются дополнительные диагностические данные
  • для некоторых keyword (например, if/then/else) ошибки могут агрегироваться из нескольких веток схемы
  • порядок ошибок соответствует порядку обхода схемы

Поведение при вложенных структурах

Вложенные объекты формируют составные пути:

instancePath: "/user/profile/contacts/0/email"

Это означает:

  • объект user
  • внутри profile
  • массив contacts
  • первый элемент массива
  • поле email

Такая структура позволяет точно локализовать проблему даже в глубоко вложенных данных.

Ошибки комбинированных схем

При использовании конструкций:

  • anyOf
  • oneOf
  • allOf

объекты ошибок могут содержать:

  • несколько альтернативных путей schemaPath
  • дополнительные пояснения в message
  • вложенные причины, объединённые в одну или несколько ошибок

Особенно это заметно в случаях, когда данные частично удовлетворяют нескольким веткам схемы, но не проходят ни одну полностью.

Использование keyword-dependent структуры params

Разные keyword формируют разные структуры params:

additionalProperties

params: { additionalProperty: "extraField" }

pattern

params: { pattern: "^[a-z]+$" }

format

params: { format: "email" }

Это позволяет программно обрабатывать ошибки без анализа текстового сообщения.

Роль message в пользовательской логике

Поле message часто рассматривается как вспомогательное, поскольку:

  • не гарантирует стабильность формулировки
  • зависит от версии Ajv
  • может быть локализовано

Поэтому основная логика обработки ошибок строится на keyword и params, а message используется для отображения.

Стабильность структуры объекта ошибки

Несмотря на различия конфигураций, базовая структура ошибок Ajv остаётся стабильной:

  • instancePath — всегда указывает на данные
  • schemaPath — всегда указывает на правило
  • keyword — определяет тип ошибки
  • params — содержит контекст нарушения

Эта стабильность позволяет использовать ошибки Ajv как основу для построения систем валидации, логирования и трансформации данных без привязки к текстовым сообщениям.

Оглавление