Первая схема валидации

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

Простейшая схема описывает строку:

import { z } from "zod";

const stringSchema = z.string();

Такая конструкция задаёт правило: значение должно быть строкой. Любое другое значение будет считаться невалидным.

Аналогично создаются схемы для чисел и булевых значений:

const numberSchema = z.number();
const booleanSchema = z.boolean();

Каждая из них является полноценным объектом схемы, поддерживающим методы валидации, трансформации и композиции.

Установка и базовая подготовка

Работа начинается с установки библиотеки:

npm install zod

После установки импортируется основной объект z, через который строятся все схемы.

import { z } from "zod";

Архитектура библиотеки полностью основана на цепочках методов и неизменяемых объектах схем.

Первая схема: строка как базовый тип

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

Базовая проверка строки

const nameSchema = z.string();

Ограничения длины

const nameSchema = z.string().min(3).max(50);

Здесь задаются правила:

  • минимальная длина — 3 символа
  • максимальная длина — 50 символов

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

Проверка формата

const emailSchema = z.string().email();

Метод email() добавляет проверку на соответствие стандартному email-формату.

Дополнительно можно использовать регулярные выражения:

const usernameSchema = z.string().regex(/^[a-zA-Z0-9_]+$/);

Создание объекта как первой сложной схемы

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

const userSchema = z.object({
  name: z.string(),
  age: z.number(),
});

Здесь определяется структура объекта:

  • name должен быть строкой
  • age должен быть числом

Такая схема проверяет сразу всю структуру данных.

Валидация данных через parse

Основной механизм проверки — метод parse.

const result = userSchema.parse({
  name: "Alex",
  age: 25,
});

Если данные корректны, возвращается исходный объект без изменений.

Если данные не соответствуют схеме, выбрасывается исключение.

Пример некорректных данных:

userSchema.parse({
  name: "Alex",
  age: "25",
});

Здесь age передан как строка, что нарушает схему.

Безопасная валидация через safeParse

Для ситуаций, где исключения нежелательны, используется safeParse.

const result = userSchema.safeParse({
  name: "Alex",
  age: "25",
});

Результат имеет структуру:

{
  success: false,
  error: ZodError,
}

или при успехе:

{
  success: true,
  data: { name: "Alex", age: 25 }
}

Такой подход позволяет явно обрабатывать ошибки без прерывания выполнения программы.

Расширение первой схемы через optional и default

Схемы можно расширять, делая поля необязательными.

const userSchema = z.object({
  name: z.string(),
  age: z.number().optional(),
});

Поле age может отсутствовать.

Также можно задать значение по умолчанию:

const userSchema = z.object({
  name: z.string(),
  role: z.string().default("user"),
});

Если role не передан, автоматически подставится "user".

Композиция схем и переиспользование

Схемы можно выделять отдельно и переиспользовать.

const nameSchema = z.string().min(2);

const userSchema = z.object({
  name: nameSchema,
  admin: z.boolean(),
});

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

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

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

const addressSchema = z.object({
  city: z.string(),
  zip: z.string(),
});

const userSchema = z.object({
  name: z.string(),
  address: addressSchema,
});

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

Работа с массивами

Схемы поддерживают массивы однотипных значений.

const tagsSchema = z.array(z.string());

Пример проверки:

tagsSchema.parse(["js", "zod", "validation"]);

Также можно комбинировать с ограничениями:

const tagsSchema = z.array(z.string()).min(1).max(5);

Преобразование значений на этапе валидации

Схема может не только проверять, но и изменять данные.

const numberSchema = z.string().transform((val) => Number(val));

Пример:

numberSchema.parse("123"); // 123

Такой подход позволяет обрабатывать входные данные из внешних источников, например HTTP-запросов.

Обработка ошибок валидации

Ошибки в Zod имеют структурированный формат.

try {
  userSchema.parse({
    name: "A",
    age: "text",
  });
} catch (e) {
  console.log(e.errors);
}

Каждая ошибка содержит:

  • путь к полю
  • сообщение
  • код типа ошибки

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

Комбинирование базовых схем в реальных структурах

Типичный пример первой полноценной схемы включает несколько уровней:

const productSchema = z.object({
  id: z.string(),
  title: z.string().min(3),
  price: z.number().positive(),
  tags: z.array(z.string()).optional(),
});

Такая схема уже описывает реальную бизнес-структуру данных и может использоваться в API, формах и сервисах обработки данных.

Логика построения первой схемы

Первая схема всегда формируется из нескольких принципов:

  • выбор базового типа (string, number, object)
  • добавление ограничений (min, max, regex)
  • уточнение структуры (object, array)
  • настройка поведения (optional, default, transform)

Эта комбинация формирует основу всей системы валидации, на которой строятся более сложные сценарии работы с данными.

Оглавление