Параметр skipMissingProperties

Параметр skipMissingProperties относится к опциям функции validate и validateSync библиотеки class-validator и управляет тем, будут ли проверяться свойства, отсутствующие в объекте в момент валидации.

Поведение параметра

При включении skipMissingProperties: true все свойства DTO, которые не присутствуют в объекте, исключаются из процесса валидации. Это означает:

  • отсутствующие поля не приводят к ошибкам;
  • валидаторы (@IsString, @IsNumber и т.д.) для таких полей не выполняются;
  • проверка выполняется только для реально переданных значений.

Если параметр отключён (false или не задан), то:

  • отсутствующие свойства могут приводить к ошибкам валидации, если на них навешаны ограничения;
  • поведение становится более строгим и соответствует полной проверке DTO.

Базовый пример

import { validate } from "class-validator";
import { IsString, IsInt } from "class-validator";

class UserDto {
  @IsString()
  name;

  @IsInt()
  age;
}

const dto = {
  name: "Alex"
};

validate(dto, { skipMissingProperties: true }).then(errors => {
  console.log(errors);
});

В данном случае:

  • name проверяется;
  • age отсутствует, но ошибка не возникает, потому что включён skipMissingProperties.

Поведение без skipMissingProperties

validate(dto, { skipMissingProperties: false });

Результат:

  • поле age отсутствует;
  • валидатор @IsInt() не получает значение;
  • возникает ошибка валидации, если поле считается обязательным по правилам DTO.

Использование в PATCH и PUT запросах

skipMissingProperties тесно связан с семантикой HTTP-методов:

  • PUT — полное обновление ресурса Все поля должны быть переданы, валидация строгая.

  • PATCH — частичное обновление Передаются только изменяемые поля.

Для PATCH типичная конфигурация:

validate(dto, { skipMissingProperties: true });

Это позволяет:

  • обновлять только часть сущности;
  • не требовать полного DTO на входе;
  • избегать ошибок из-за отсутствующих полей.

Взаимодействие с @IsOptional

Важно различать skipMissingProperties и декоратор @IsOptional.

import { IsOptional, IsString } from "class-validator";

class UserDto {
  @IsOptional()
  @IsString()
  nickname;
}
  • @IsOptional() — применяется на уровне поля;
  • skipMissingProperties — применяется на уровне всей валидации.

Различия:

  • @IsOptional() отключает валидацию только для undefined значений конкретного свойства;
  • skipMissingProperties полностью исключает отсутствующее поле из проверки, независимо от декораторов.

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

Отличие от skipUndefinedProperties

В некоторых версиях или конфигурациях можно встретить похожий параметр skipUndefinedProperties.

Разграничение:

  • skipMissingProperties — пропускает свойства, которых нет в объекте вообще;
  • skipUndefinedProperties — пропускает свойства, которые существуют, но равны undefined.

Пример различия:

const dto = {
  name: undefined
};
  • при skipMissingProperties: true поле считается отсутствующим и игнорируется;
  • при skipUndefinedProperties: true также игнорируется, но при этом поле формально существует.

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

При использовании с ValidateNested поведение распространяется рекурсивно:

import { ValidateNested, IsString } from "class-validator";

class ProfileDto {
  @IsString()
  bio;
}

class UserDto {
  @ValidateNested()
  profile;
}

Если profile отсутствует в объекте и включён skipMissingProperties, то:

  • вложенная валидация ProfileDto не запускается;
  • ошибки внутри вложенного объекта не формируются.

Частичные DTO и трансформация данных

В связке с class-transformer поведение становится более предсказуемым при обработке входных данных API:

import { plainToInstance } from "class-transformer";
import { validate } from "class-validator";

const dto = plainToInstance(UserDto, requestBody);

validate(dto, { skipMissingProperties: true });

Если поле не пришло в requestBody:

  • оно не будет добавлено в экземпляр DTO;
  • валидация его не затронет.

Типичные ошибки при использовании

  • Ожидание, что skipMissingProperties заменяет @IsOptional() Это разные механизмы, работающие на разных уровнях.

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

  • Игнорирование вложенных объектов Часто ожидается, что nested-валидация будет строгой, но она также пропускается при отсутствии данных.

Практическое поведение валидации

Комбинация декораторов и опций формирует итоговую модель:

  • присутствует поле → проверяется всеми декораторами;
  • отсутствует поле → пропускается при skipMissingProperties: true;
  • @IsOptional() дополнительно смягчает поведение на уровне свойства;
  • ValidateNested() активируется только при наличии вложенного объекта.

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

Оглавление