Структура объекта ValidationError

ValidationError в Yup представляет собой специализированный объект ошибки, который формируется при нарушении правил валидации схемы. Он содержит структурированную информацию о том, какое именно правило было нарушено, где в структуре данных это произошло и какие дополнительные детали могут быть полезны для обработки ошибки на уровне приложения.

При возникновении ошибки валидации Yup возвращает экземпляр ValidationError, который расширяет стандартный Error и добавляет ряд специфичных для библиотеки свойств.

name

Поле name почти всегда имеет значение "ValidationError". Оно используется для идентификации типа ошибки и позволяет отличать ошибки валидации от других исключений.

message

message содержит человекочитаемое описание первой обнаруженной ошибки. Это наиболее краткое представление проблемы, например:

"email is a required field"

или

"password must be at least 8 characters"

Важно учитывать, что message отражает только одну ошибку, даже если их несколько.

path

path указывает на путь к проблемному полю валидации. Это строка, отражающая вложенность структуры данных:

"user.email"

или

"items[0].price"

Если ошибка относится к корневому объекту, значение path может быть undefined.

errors: массив сообщений

Поле errors представляет собой массив строк, содержащих все сообщения ошибок, относящихся к текущему узлу валидации.

[
  "password is too short",
  "password must contain a number"
]

В отличие от message, здесь сохраняются все обнаруженные нарушения правил. Это особенно важно при использовании .validate({ abortEarly: false }), когда Yup не останавливается на первой ошибке.

inner: вложенные ValidationError

Поле inner содержит массив объектов ValidationError, каждый из которых относится к конкретной ветке вложенной структуры.

Это ключевой механизм для работы с вложенными объектами и массивами:

[
  ValidationError,
  ValidationError
]

Каждый элемент inner включает собственные path, message, type и другие поля, позволяя точно локализовать ошибку внутри сложной схемы.

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

type: тип нарушения правила

Поле type указывает на конкретное правило Yup, которое было нарушено:

  • "required"
  • "min"
  • "max"
  • "email"
  • "matches"
  • "oneOf"

Пример:

type: "min"

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

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

params содержит дополнительные данные, связанные с правилом, которое не было выполнено. Эти данные зависят от конкретного валидатора.

Пример для min:

params: {
  min: 8,
  value: 5
}

Пример для matches:

params: {
  regex: /[A-Z]/,
  value: "password"
}

params позволяет строить динамические сообщения об ошибках или локализацию без потери контекста.

value и originalValue

Поле value содержит значение, которое прошло проверку и вызвало ошибку. Оно может быть преобразованным в процессе кастомных трансформаций схемы.

В некоторых сценариях доступно поле originalValue, отражающее исходное значение до любых преобразований transform().

Разделение этих двух значений важно при отладке сложных схем, где данные модифицируются до этапа проверки.

stack

Как и стандартная ошибка JavaScript, ValidationError содержит поле stack, представляющее стек вызовов в момент возникновения ошибки.

stack: "ValidationError: email is required\n    at ... "

Оно используется преимущественно для отладки и редко участвует в бизнес-логике.

Поведение при множественных ошибках

Yup поддерживает два режима формирования ошибки:

  • abortEarly: true — возвращается только первая ошибка, errors содержит один элемент, inner обычно пустой.
  • abortEarly: false — собираются все ошибки, заполняются errors и inner.

При отключении раннего прерывания структура ValidationError становится более насыщенной, и обработка ошибок требует обхода массива inner.

Вложенные структуры и путь path

При работе с объектами и массивами поле path формируется по правилам:

  • точечная нотация для объектов (user.profile.name)
  • индексная нотация для массивов (items[2].price)

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

Особенности агрегации ошибок

В случае сложных схем Yup формирует иерархию ValidationError, где:

  • корневой объект содержит агрегированную информацию
  • inner хранит детализированные ошибки по каждому узлу
  • errors дублирует сообщения на текущем уровне

Такая структура позволяет одновременно:

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

Использование структуры ValidationError при обработке данных

При обработке результата валидации обычно анализируются три уровня:

  • message — для быстрого отображения одной ошибки
  • errors — для списка сообщений на уровне поля
  • inner — для построения карты ошибок по форме

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

Оглавление