Типы ошибок

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

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

Каждая ошибка валидации в Ajv представляет собой объект с фиксированным набором полей:

  • instancePath — путь к данным, где обнаружено несоответствие
  • schemaPath — путь к правилу схемы, которое было нарушено
  • keyword — ключевое слово JSON Schema, вызвавшее ошибку
  • params — дополнительные параметры, уточняющие причину ошибки
  • message — человекочитаемое описание проблемы
  • schema — значение схемы, участвующее в проверке
  • data — фактическое значение данных

Пример типичной ошибки:

{
  "instancePath": "/age",
  "schemaPath": "#/properties/age/type",
  "keyword": "type",
  "params": { "type": "number" },
  "message": "must be number"
}

Ошибки типа (type)

Ошибка type возникает при несоответствии значения ожидаемому типу данных. Это одна из самых частых ошибок.

Примеры:

  • ожидался string, получен number
  • ожидался array, получен object
{
  "keyword": "type",
  "instancePath": "/name",
  "params": { "type": "string" },
  "message": "must be string"
}

Ошибки обязательных полей (required)

Ключевое слово required вызывает ошибки при отсутствии обязательных свойств в объекте.

{
  "keyword": "required",
  "instancePath": "",
  "params": { "missingProperty": "email" },
  "message": "must have required property 'email'"
}

Особенность таких ошибок — instancePath указывает на объект, а не на конкретное поле.

Ошибки дополнительных свойств (additionalProperties)

При строгой схеме запрещены лишние поля.

{
  "keyword": "additionalProperties",
  "instancePath": "",
  "params": { "additionalProperty": "unexpectedField" },
  "message": "must NOT have additional properties"
}

Эти ошибки часто возникают при интеграции API, когда структура данных изменяется без обновления схемы.

Ошибки перечислений (enum)

Ключевое слово enum ограничивает набор допустимых значений.

{
  "keyword": "enum",
  "instancePath": "/status",
  "params": { "allowedValues": ["active", "disabled"] },
  "message": "must be equal to one of the allowed values"
}

Ошибки констант (const)

const требует точного совпадения значения.

{
  "keyword": "const",
  "instancePath": "/role",
  "params": { "allowedValue": "admin" },
  "message": "must be constant"
}

Ошибки формата (format)

Проверка форматов (email, uri, date-time и др.) генерирует ошибки при несоответствии шаблону.

{
  "keyword": "format",
  "instancePath": "/email",
  "params": { "format": "email" },
  "message": "must match format \"email\""
}

Форматная валидация зависит от подключённых форматов Ajv и может расширяться плагинами.

Ошибки шаблона (pattern)

Регулярные выражения в JSON Schema проверяются через pattern.

{
  "keyword": "pattern",
  "instancePath": "/username",
  "params": { "pattern": "^[a-zA-Z0-9_]+$" },
  "message": "must match pattern \"^[a-zA-Z0-9_]+$\""
}

Ошибки ограничений чисел

Для числовых значений применяются ограничения:

  • minimum
  • maximum
  • exclusiveMinimum
  • exclusiveMaximum
  • multipleOf

Пример:

{
  "keyword": "minimum",
  "instancePath": "/age",
  "params": { "comparison": ">=", "limit": 18 },
  "message": "must be >= 18"
}

Ошибки длины строк и массивов

Используются ключевые слова:

  • minLength
  • maxLength
  • minItems
  • maxItems
{
  "keyword": "minLength",
  "instancePath": "/password",
  "params": { "limit": 8 },
  "message": "must NOT have fewer than 8 characters"
}

Ошибки зависимостей (dependencies)

Схема может требовать наличие дополнительных полей при наличии определённого свойства.

{
  "keyword": "dependencies",
  "instancePath": "",
  "params": { "property": "creditCard" },
  "message": "must have property 'billingAddress'"
}

Ошибки логических операторов схемы

oneOf

Ошибка возникает, если данные соответствуют более чем одной или ни одной схеме.

{
  "keyword": "oneOf",
  "instancePath": "",
  "message": "must match exactly one schema in oneOf"
}

anyOf

Ошибка возникает, если данные не соответствуют ни одной схеме.

{
  "keyword": "anyOf",
  "instancePath": "",
  "message": "must match some schema in anyOf"
}

allOf

Ошибка возникает при несоответствии любой из вложенных схем.

{
  "keyword": "allOf",
  "instancePath": "",
  "message": "must match all schemas in allOf"
}

not

Инвертированная проверка: данные не должны соответствовать схеме.

{
  "keyword": "not",
  "instancePath": "",
  "message": "must NOT be valid"
}

Ошибки приведения типов

При включённой опции coerceTypes Ajv пытается преобразовывать значения. Ошибки возникают, когда приведение невозможно или приводит к NaN.

Пример ситуации:

  • строка "abc" не может быть преобразована в число

Ошибки кастомных ключевых слов

Ajv поддерживает расширение через пользовательские keywords. Ошибки таких валидаторов формируются вручную и могут содержать произвольные message и params.

ajv.addKeyword({
  keyword: "isPositive",
  validate: (schema, data) => data > 0,
  error: { message: "must be positive number" }
});

Ошибки компиляции схем

Отдельный класс ошибок возникает до выполнения валидации:

  • некорректная JSON Schema
  • неизвестные ключевые слова
  • нарушение режима strict
  • циклические ссылки

Пример сообщения:

strict mode: unknown keyword "foo"

Такие ошибки выбрасываются через исключения, а не через массив errors.

Ошибки конфигурации Ajv

Ошибки конфигурации связаны с настройками экземпляра:

  • конфликт версий draft JSON Schema
  • неверные параметры allErrors, strict, removeAdditional
  • отсутствие подключённых форматов

Расширенный формат ошибок (Ajv v8)

В версии Ajv v8 используется поле instancePath вместо устаревшего dataPath, что изменяет структуру диагностики.

Ключевые различия:

  • instancePath — JSON Pointer к данным
  • schemaPath — путь к узлу схемы
  • улучшенная совместимость с JSON Pointer стандартом

Множественные ошибки (allErrors)

При включённой опции allErrors возвращается массив всех найденных ошибок вместо первой.

Это влияет на структуру диагностики:

  • увеличивается количество объектов ошибок
  • упрощается отображение полной картины несоответствий
  • усложняется приоритизация исправлений

Ошибки строгого режима

В строгом режиме Ajv фиксирует дополнительные проблемы:

  • неиспользуемые ключевые слова
  • подозрительные конструкции схем
  • несовместимость с JSON Schema спецификацией

Такие ошибки могут блокировать компиляцию схемы.

Кастомизация сообщений ошибок

Плагин errorMessage позволяет заменять стандартные сообщения:

{
  "keyword": "errorMessage",
  "message": "Некорректный формат данных"
}

Это влияет только на message, не изменяя структуру keyword, params и путей.

Пример комплексного набора ошибок

При сложной валидации одного объекта могут одновременно возникать несколько типов ошибок:

  • отсутствие обязательного поля (required)
  • неверный тип (type)
  • нарушение диапазона (minimum)
  • несоответствие формату (format)
  • лишние свойства (additionalProperties)

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

Оглавление