Объекты: object schema

Валидация объектов в Yup строится вокруг метода yup.object(), который позволяет описывать структуру сложных данных, состоящих из вложенных полей. Объектная схема представляет собой контейнер для набора валидаторов, каждый из которых применяется к конкретному ключу объекта.

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

Базовое создание объектной схемы

Объектная схема создаётся через yup.object() без параметров или с передачей структуры через shape().

import * as yup from 'yup';

const schema = yup.object({
  name: yup.string().required(),
  age: yup.number().min(18),
});

Альтернативный вариант с явным указанием структуры:

const schema = yup.object().shape({
  name: yup.string().required(),
  age: yup.number().min(18),
});

Оба варианта эквивалентны, однако использование shape() чаще применяется при динамическом построении схем.

Проверка вложенных объектов

Объектные схемы поддерживают рекурсивное описание вложенных структур. Каждый вложенный объект также является отдельной схемой yup.object().

const schema = yup.object({
  user: yup.object({
    id: yup.number().required(),
    profile: yup.object({
      email: yup.string().email().required(),
      phone: yup.string(),
    }),
  }),
});

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

Обязательные и необязательные поля

По умолчанию поля считаются необязательными, если не указано иное. Для строгой проверки используется required().

const schema = yup.object({
  username: yup.string().required(),
  nickname: yup.string(), // необязательное поле
});

Объект целиком может быть отмечен как обязательный:

const schema = yup.object().required();

Строгий режим и запрет лишних полей

Метод noUnknown() позволяет запретить наличие полей, не описанных в схеме.

const schema = yup.object({
  name: yup.string(),
}).noUnknown();

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

Строгий режим strict() отключает автоматические преобразования значений:

const schema = yup.object({
  age: yup.number(),
}).strict();

Значения по умолчанию

Объектные схемы могут содержать значения по умолчанию через default().

const schema = yup.object({
  role: yup.string().default('user'),
});

Если поле отсутствует в исходных данных, оно будет заполнено значением по умолчанию при трансформации.

Объединение схем

Схемы могут быть расширены через concat(), что позволяет модульно строить объектные структуры.

const baseSchema = yup.object({
  id: yup.number().required(),
});

const extendedSchema = baseSchema.concat(
  yup.object({
    name: yup.string().required(),
  })
);

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

Условная валидация объектов

Метод when() позволяет изменять структуру или правила в зависимости от других полей.

const schema = yup.object({
  type: yup.string(),
  company: yup.string().when('type', {
    is: 'business',
    then: (schema) => schema.required(),
    otherwise: (schema) => schema.notRequired(),
  }),
});

Объектная схема может динамически адаптироваться к входным данным.

Кастомная валидация объектов

Метод test() применяется для создания пользовательских правил на уровне объекта.

const schema = yup.object({
  password: yup.string(),
  confirmPassword: yup.string(),
}).test('match', 'Пароли не совпадают', (value) => {
  return value?.password === value?.confirmPassword;
});

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

Работа с неизвестными структурами

В случаях, когда структура объекта заранее неизвестна, используется свободная схема:

const schema = yup.object().shape({
  metadata: yup.object().noUnknown(false),
});

Также возможно использование lazy() для динамического построения схем:

const schema = yup.object({
  config: yup.lazy((value) => {
    if (typeof value === 'object') {
      return yup.object({
        key: yup.string(),
      });
    }
    return yup.mixed();
  }),
});

Извлечение и трансформация данных

Объектные схемы поддерживают трансформацию входных данных через transform().

const schema = yup.object({
  tags: yup.array().transform((value) =>
    typeof value === 'string' ? value.split(',') : value
  ),
});

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

Частичная валидация структуры

Метод pick() позволяет выделить подмножество полей схемы.

const fullSchema = yup.object({
  id: yup.number(),
  name: yup.string(),
  age: yup.number(),
});

const partialSchema = fullSchema.pick(['id', 'name']);

Метод omit() выполняет обратную операцию:

const schemaWithoutAge = fullSchema.omit(['age']);

Вложенные массивы объектов

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

const schema = yup.object({
  users: yup.array().of(
    yup.object({
      id: yup.number().required(),
      email: yup.string().email(),
    })
  ),
});

Каждый элемент массива проходит отдельную валидацию согласно объектной схеме.

Доступ к вложенным полям схемы

Функция reach() позволяет получить доступ к глубоко вложенному полю схемы.

const fieldSchema = yup.reach(schema, 'user.profile.email');

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

Слияние объектных схем

При необходимости несколько схем могут объединяться в одну структуру через повторное использование object() и shape().

const addressSchema = yup.object({
  city: yup.string(),
  street: yup.string(),
});

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

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

Поведение при отсутствии значений

Если объект не передан полностью, поведение зависит от конфигурации схемы:

  • required() — объект обязателен
  • отсутствие required() — допускается undefined
  • default() — применяется подстановка значений
const schema = yup.object({
  settings: yup.object().default({
    theme: 'dark',
  }),
});

Особенности преобразования объектов

При валидации Yup может выполнять преобразование типов, включая:

  • удаление undefined полей
  • применение default()
  • приведение строк к объектам при кастомных transform()

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

Композиция сложных структур

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

Оглавление