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

ZodError — центральный объект, через который библиотека Zod возвращает информацию о неуспешной валидации данных. Он агрегирует все найденные нарушения схемы и предоставляет как «сырое» представление ошибок, так и инструменты для их преобразования в удобные структуры.

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

Базовая структура ZodError

Объект ZodError имеет несколько ключевых полей:

  • name — строковое значение "ZodError", идентификатор типа ошибки
  • issues — массив объектов ZodIssue, содержащий все ошибки валидации
  • message — агрегированное текстовое описание ошибок
  • stack — стек вызовов (обычно используется для отладки)

Главная часть структуры — это issues, поскольку именно она содержит полную информацию о каждом нарушении схемы.

Массив issues как ядро модели ошибки

issues представляет собой массив, где каждый элемент описывает конкретную проблему валидации.

Каждый элемент массива — это объект ZodIssue, который содержит:

  • code — тип ошибки
  • path — путь к значению, которое не прошло проверку
  • message — человекочитаемое описание ошибки
  • expected — ожидаемый тип или значение (в зависимости от кода)
  • received — фактическое значение, которое было получено

Дополнительно некоторые типы ошибок могут содержать расширенные поля (например, для union-ошибок или строковых ограничений).

Поле path: навигация к источнику ошибки

path — один из наиболее важных элементов структуры ZodIssue.

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

Примеры структуры path:

  • [] — ошибка на корневом уровне
  • ["user"] — ошибка внутри объекта user
  • ["user", "email"] — ошибка в поле email объекта user
  • ["items", 2, "price"] — ошибка внутри массива на конкретной позиции

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

Поле code: классификация ошибок

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

Наиболее распространённые значения:

  • invalid_type — несоответствие типа (например, строка вместо числа)
  • too_small — значение меньше минимально допустимого
  • too_big — значение больше максимально допустимого
  • invalid_string — строка не соответствует формату (например, email)
  • unrecognized_keys — лишние ключи в объекте
  • custom — ошибка, заданная через пользовательскую валидацию
  • invalid_union — ни один вариант union-типа не подошёл

Каждый code определяет набор дополнительных полей в ZodIssue.

Структура ZodIssue при разных типах ошибок

Ошибка типа invalid_type

Содержит:

  • expected — ожидаемый тип
  • received — фактический тип

Пример логики:

  • expected: "string"
  • received: "number"

Ошибки ограничений (too_small / too_big)

Содержат:

  • minimum / maximum — границы
  • inclusive — включительность границы
  • type — тип ограничения (string, number, array)

invalid_string

Используется при проверке форматов строк:

  • validation — тип проверки (email, url, uuid, regex и т.д.)

custom

Пользовательские ошибки через refine или superRefine:

  • params — дополнительные параметры, переданные разработчиком

invalid_union

Содержит:

  • unionErrors — массив ZodError для каждой неудачной ветки union

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

Вложенные ошибки и рекурсия структуры

Одной из ключевых особенностей ZodError является рекурсивность.

ZodError может содержать внутри себя другие ZodError через:

  • unionErrors
  • nested issues в path

Это позволяет строить дерево ошибок, отражающее структуру валидируемого объекта.

Методы format и flatten

format()

Метод format() преобразует массив issues в вложенный объект, где структура повторяет исходные данные.

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

  • ключи соответствуют полям объекта
  • значения содержат сообщения об ошибках
  • вложенность сохраняется

Пример логики результата:

  • user:

    • email: “Invalid email”
    • age: “Too small”

flatten()

Метод flatten() упрощает структуру ошибки до двух частей:

  • formErrors — ошибки общего уровня
  • fieldErrors — объект, где ключи соответствуют полям

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

  • удаляет вложенность
  • объединяет сообщения в массивы строк
  • удобен для UI-форм

Агрегирование сообщений

Поле message в ZodError формируется автоматически как объединение всех сообщений из issues.

Оно:

  • не структурировано
  • предназначено для логирования
  • не отражает иерархию ошибок

Особенности поведения при валидации

При использовании строгих схем:

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

Это делает ZodError детализированным источником диагностики.

Работа с путями и вложенными структурами

Комбинация path + issues позволяет:

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

Глубина вложенности не ограничена, что особенно важно для сложных схем объектов и массивов.

Иерархия данных внутри ZodError

Структурно объект можно представить так:

  • ZodError

    • issues[]

      • ZodIssue

        • code
        • path
        • message
        • дополнительные поля

    • methods:

      • format()
      • flatten()

Роль ZodError в системе валидации

ZodError является финальным агрегатором всех проверок, выполняемых схемой. Он:

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

Его структура ориентирована на точную диагностику и последующую обработку в прикладной логике без потери информации о происхождении ошибки.

Оглавление