| Option |
Type |
Description |
enableDebugMessages |
boolean |
If set to true, validator will print extra warning messages to the console when something is not right. |
skipUndefinedProperties |
boolean |
If set to true then validator will skip validation of all properties that are undefined in the validating object. |
skipNullProperties |
boolean |
If set to true then validator will skip validation of all properties that are null in the validating object. |
skipMissingProperties |
boolean |
If set to true then validator will skip validation of all properties that are null or undefined in the validating object. |
whitelist |
boolean |
If set to true, validator will strip validated (returned) object of any properties that do not use any validation decorators. |
forbidNonWhitelisted |
boolean |
If set to true, instead of stripping non-whitelisted properties validator will throw an exception. |
forbidUnknownValues |
boolean |
If set to true, attempts to validate unknown objects fail immediately. |
disableErrorMessages |
boolean |
If set to true, validation errors will not be returned to the client. |
errorHttpStatusCode |
number |
This setting allows you to specify which exception type will be used in case of an error. By default it throws BadRequestException. |
exceptionFactory |
Function |
Takes an array of the validation errors and returns an exception object to be thrown. |
groups |
string[] |
Groups to be used during validation of the object. |
always |
boolean |
Set default for always option of decorators. Default can be overridden in decorator options. |
strictGroups |
boolean |
If groups is not given or is empty, ignore decorators with at least one group. |
dismissDefaultMessages |
boolean |
If set to true, the validation will not use default messages. Error message always will be undefined if
its not explicitly set. |
validationError.target |
boolean |
Indicates if target should be exposed in ValidationError. |
validationError.value |
boolean |
Indicates if validated value should be exposed in ValidationError. |
stopAtFirstError |
boolean |
When set to true, validation of the given property will stop after encountering the first error. Defaults to false. |
errorFormat |
'list' | 'grouped' |
Specifies the format of validation error messages. 'list' (default) returns an array of error message strings. 'grouped' returns an object with property paths as keys and arrays of unmodified error messages as values, preserving custom validation messages without prepending parent path prefixes. |
> info **Notice** Find more information about the `class-validator` package in its [repository](https://github.com/typestack/class-validator).
#### Auto-validation
Start by binding `ValidationPipe` at the application level, so that every endpoint is protected from receiving invalid data.
```typescript
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(new ValidationPipe());
await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();
```
To test the pipe, create a basic endpoint:
```typescript
@Post()
create(@Body() createUserDto: CreateUserDto) {
return 'This action adds a new user';
}
```
> info **Hint** TypeScript does not emit metadata for **generics or interfaces**, so `ValidationPipe` cannot validate DTOs declared with them. Use concrete classes for your DTOs.
> info **Hint** Don't import DTOs with a type-only import, because type-only imports are erased at runtime. Write `import { CreateUserDto }` instead of `import type { CreateUserDto }`.
Next, add validation rules to the `CreateUserDto` with the decorators provided by the `class-validator` package (see the [full list](https://github.com/typestack/class-validator#validation-decorators)). Every route that uses `CreateUserDto` then enforces these rules.
```typescript
import { IsEmail, IsNotEmpty } from 'class-validator';
export class CreateUserDto {
@IsEmail()
email: string;
@IsNotEmpty()
password: string;
}
```
With these rules in place, a request whose body contains an invalid `email` property receives a `400 Bad Request` response with the following body:
```json
{
"statusCode": 400,
"error": "Bad Request",
"message": ["email must be an email"]
}
```
`ValidationPipe` validates other parts of the request as well. For example, to accept only numeric values for the `:id` path parameter, use the following construct:
```typescript
@Get(':id')
findOne(@Param() params: FindOneParams) {
return 'This action returns a user';
}
```
Like a DTO, `FindOneParams` is a class that defines validation rules with `class-validator`:
```typescript
import { IsNumberString } from 'class-validator';
export class FindOneParams {
@IsNumberString()
id: string;
}
```
#### Disable detailed errors
Error messages explain what was wrong with a request, but some production environments prefer not to expose them. To disable detailed errors, pass an options object to the `ValidationPipe`:
```typescript
app.useGlobalPipes(
new ValidationPipe({
disableErrorMessages: true,
}),
);
```
As a result, the response body no longer contains detailed error messages.
#### Stripping properties
`ValidationPipe` can also filter out properties that the route handler should not receive. When you **whitelist** the acceptable properties, any property not included in the whitelist is stripped from the resulting object. For example, if the handler expects `email` and `password`, but a request also includes an `age` property, `age` is removed from the resulting DTO. To enable this behavior, set `whitelist` to `true`.
```typescript
app.useGlobalPipes(
new ValidationPipe({
whitelist: true,
}),
);
```
With this option enabled, properties without any decorator in the validation class are removed.
Alternatively, you can reject requests that contain non-whitelisted properties with an error response. To do so, set `forbidNonWhitelisted` to `true` in addition to `whitelist`.
#### Transform payload objects
Payloads arrive over the network as plain JavaScript objects. `ValidationPipe` can transform them into instances of their DTO classes. To enable auto-transformation, set `transform` to `true`. You can do this at the method level:
```typescript
@Post()
@UsePipes(new ValidationPipe({ transform: true }))
async create(@Body() createCatDto: CreateCatDto) {
this.catsService.create(createCatDto);
}
```
To enable this behavior globally, set the option on a global pipe:
```typescript
app.useGlobalPipes(
new ValidationPipe({
transform: true,
}),
);
```
With auto-transformation enabled, `ValidationPipe` also converts primitive types. In the following example, the `findOne()` method takes the `id` path parameter as an argument:
```typescript
@Get(':id')
findOne(@Param('id') id: number) {
console.log(typeof id === 'number'); // true
return 'This action returns a user';
}
```
Path parameters and query parameters always arrive as strings. Because the method signature declares `id` as a `number`, `ValidationPipe` converts the string identifier to a number.
#### Explicit conversion
The previous section showed how `ValidationPipe` implicitly converts query and path parameters based on their declared types. That conversion requires auto-transformation to be enabled.
With auto-transformation disabled, you can convert values explicitly with `ParseIntPipe` or `ParseBoolPipe`. There is no `ParseStringPipe`, because path and query parameters are already strings.
```typescript
@Get(':id')
findOne(
@Param('id', ParseIntPipe) id: number,
@Query('sort', ParseBoolPipe) sort: boolean,
) {
console.log(typeof id === 'number'); // true
console.log(typeof sort === 'boolean'); // true
return 'This action returns a user';
}
```
> info **Hint** The `ParseIntPipe` and `ParseBoolPipe` are exported from the `@nestjs/common` package.
#### Mapped types
Features such as **CRUD** (Create/Read/Update/Delete) often need several variants of a base type. Nest provides utility functions that perform these type transformations.
> warning **Warning** If your application uses the `@nestjs/swagger` package, see [this chapter](/openapi/mapped-types) for more information about mapped types. Likewise, if you use the `@nestjs/graphql` package, see [this chapter](/graphql/mapped-types). Both packages rely heavily on type metadata, so they export their own versions of these utilities. Importing them from `@nestjs/mapped-types` instead of `@nestjs/swagger` or `@nestjs/graphql` can cause undocumented side effects.
Input validation types (DTOs) often come in **create** and **update** variants of the same type: the **create** variant requires all fields, while the **update** variant makes them optional. The mapped types utilities derive such variants without repeating the property declarations or their validation decorators. Consider the following **create** type:
```typescript
export class CreateCatDto {
name: string;
age: number;
breed: string;
}
```
> info **Hint** `PartialType()`, `PickType()`, `OmitType()`, and `IntersectionType()` are imported from the `@nestjs/mapped-types` package.
The `PartialType()` function returns a type (class) with all the properties of the input type set to optional:
```typescript
export class UpdateCatDto extends PartialType(CreateCatDto) {}
```
The `PickType()` function constructs a type from a subset of the input type's properties:
```typescript
export class UpdateCatAgeDto extends PickType(CreateCatDto, ['age'] as const) {}
```
The `OmitType()` function constructs a type with every property of the input type **except** the listed ones. The second argument is an array of property names:
```typescript
export class UpdateCatDto extends OmitType(CreateCatDto, ['name'] as const) {}
```
The `IntersectionType()` function combines the properties of two types into one new type (class). For example, given an additional type:
```typescript
export class AdditionalCatInfo {
color: string;
}
```
The following type contains the properties of both:
```typescript
export class UpdateCatDto extends IntersectionType(
CreateCatDto,
AdditionalCatInfo,
) {}
```
The type mapping utility functions are composable. For example, the following type has all of the properties of `CreateCatDto` except `name`, all set to optional:
```typescript
export class UpdateCatDto extends PartialType(
OmitType(CreateCatDto, ['name'] as const),
) {}
```
#### Parsing and validating arrays
TypeScript does not emit metadata for generic types such as arrays, so `ValidationPipe` cannot validate the elements of an array parameter. In the following code, the elements of `createUserDtos` are not validated:
```typescript
@Post()
createBulk(@Body() createUserDtos: CreateUserDto[]) {
return 'This action adds new users';
}
```
To validate the array, create a dedicated class with a property that wraps the array, or use the `ParseArrayPipe`:
```typescript
@Post()
createBulk(
@Body(new ParseArrayPipe({ items: CreateUserDto }))
createUserDtos: CreateUserDto[],
) {
return 'This action adds new users';
}
```
`ParseArrayPipe` is also useful for parsing query parameters. Consider a `findByIds()` method that returns users based on identifiers passed in the query string:
```typescript
@Get()
findByIds(
@Query('ids', new ParseArrayPipe({ items: Number, separator: ',' }))
ids: number[],
) {
return 'This action returns users by ids';
}
```
This construction parses and validates the query parameters of a request such as the following:
```bash
GET /?ids=1,2,3
```
#### Schema-based validation
The `StandardSchemaValidationPipe` validates values against schemas instead of decorated classes. It accepts any schema that implements the [Standard Schema](https://standardschema.dev/) specification, which includes [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and [ArkType](https://arktype.io/). The schema is the single source of truth for a payload: it validates the value at runtime, and its inferred type is the handler parameter's TypeScript type. The examples in this section use Zod.
```bash
$ npm i --save zod
```
Define a schema and infer the DTO type from it:
```typescript
import { z } from 'zod';
export const createUserSchema = z.object({
email: z.email(),
password: z.string().min(8),
displayName: z.string().max(50).optional(),
});
export type CreateUserDto = z.infer