npm install nestjs-zod # Note: zod ^3.25.0 || ^4.0.0 is also required

Check out the example app for a full example of how to integrate nestjs-zod in your nestjs application

Documentation

• Request Validation
  • createZodDto (Create a DTO from a Zod schema)
  • ZodValidationPipe (Get nestjs to validate using zod)
  • createZodValidationPipe (Creating custom validation pipe)
  • ZodValidationException
  • ZodSchemaDeclarationException
• Response Validation
  • ZodSerializerDto (Set zod DTO to serialize responses with)
  • ZodSerializerInterceptor (Get nestjs to serialize responses with zod)
  • createZodSerializerInterceptor (Creating custom serializer interceptor)
  • ZodResponse (Sync run-time, compile-time, and docs-time schemas)
  • ZodSerializationException
• OpenAPI (Swagger) support
  • cleanupOpenApiDoc (Ensure proper OpenAPI output)
  • Output schemas
  • Codecs
  • Reusable schemas
  • zodV3ToOpenAPI (⚠️ DEPRECATED)
• validate (⚠️ DEPRECATED)
• ZodGuard (⚠️ DEPRECATED)
  • createZodGuard (Creating custom guard)
• @nest-zod/z (⚠️ DEPRECATED)
  • ZodDateString
  • ZodPassword

Request Validation

createZodDto (Create a DTO from a Zod schema)

function createZodDto<TSchema extends UnknownSchema, TCodec extends boolean = false>(schema: TSchema, options?: { codec: TCodec }): ZodDto<TSchema, TCodec>;

Creates a nestjs DTO from a zod schema. These zod DTOs can be used in place of class-validator / class-transformer DTOs. Zod DTOs are responsible for three things:

1. Providing a schema for ZodValidationPipe to validate incoming client data against
2. Providing a compile-time typescript type from the Zod schema
3. Providing an OpenAPI schema when using nestjs/swagger

[!NOTE] For this feature to work, please ensure ZodValidationPipe is setup correctly

Parameters

• schema - A zod schema. You can "bring your own zod", including zod v3 schemas, v4 schemas, zod mini schemas, etc. The only requirement is that the schema has a method called parse
• options
  • options.codec - If set to true, then when serializing responses nestjs-zod will use encode instead of parse. See more information about codecs in the zod documentation

Examples

Creating a zod DTO

import { createZodDto } from 'nestjs-zod'
import { z } from 'zod'

const CredentialsSchema = z.object({
  username: z.string(),
  password: z.string(),
})

// class is required for using DTO as a type
class CredentialsDto extends createZodDto(CredentialsSchema) {}

Using a zod DTO

@Controller('auth')
class AuthController {
  async signIn(@Body() credentials: CredentialsDto) {}
}

ZodValidationPipe (Get nestjs to validate using zod)

ZodValidationPipe is needed to ensure zod DTOs actually validate incoming request data when using @Body(), @Params(), or @Query() parameter decorators

When the data is invalid it throws a ZodValidationException.

Example

Globally (recommended)

import { ZodValidationPipe } from 'nestjs-zod'
import { APP_PIPE } from '@nestjs/core'

@Module({
  providers: [
    {
      provide: APP_PIPE,
      useClass: ZodValidationPipe,
    },
  ],
})
export class AppModule {}

Locally

import { ZodValidationPipe } from 'nestjs-zod'

// controller-level
@UsePipes(ZodValidationPipe)
class AuthController {}

class AuthController {
  // route-level
  @UsePipes(ZodValidationPipe)
  async signIn() {}
}

createZodValidationPipe (Creating custom validation pipe)

export function createZodValidationPipe({ createValidationException, strictSchemaDeclaration }: ZodValidationPipeOptions = {}): ZodValidationPipeClass

Creates a custom zod validation pipe

Example

import { createZodValidationPipe } from 'nestjs-zod'

const MyZodValidationPipe = createZodValidationPipe({
  // provide custom validation exception factory
  createValidationException: (error: ZodError) =>
    new BadRequestException('Ooops'),
})

Parameters

• params.createValidationException - A callback that will be called with the zod error when a parsing error occurs. Should return a new instance of Error
• params.strictSchemaDeclaration - If true, throws a ZodSchemaDeclarationException when the pipe encounters a parameter that is not typed with a nestjs-zod DTO. It's recommended to set this to true to ensure all request data is properly validated

ZodValidationException

If the zod request parsing fails, then nestjs-zod will throw a ZodValidationException, which will result in the following HTTP response:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "code": "too_small",
      "minimum": 8,
      "type": "string",
      "inclusive": true,
      "message": "String must contain at least 8 character(s)",
      "path": ["password"]
    }
  ]
}

You can customize the exception and HTTP response by either 1) creating a custom validation pipe using createZodValidationPipe or 2) handling ZodValidationException inside an exception filter

Here is an example exception filter:

@Catch(ZodValidationException)
export class ZodValidationExceptionFilter implements ExceptionFilter {
  catch(exception: ZodValidationException) {
    exception.getZodError() // -> ZodError
  }
}

ZodSchemaDeclarationException

If strictSchemaDeclaration is set to true in createZodValidationPipe and a request parameter is not typed with a nestjs-zod DTO (e.g. using a primitive type like string or a class-validator DTO), then nestjs-zod will throw a ZodSchemaDeclarationException, which will result in the following HTTP response:

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

This is useful for catching cases during development where request data might not be properly validated. You can handle this exception in an exception filter if you want to customize the response:

@Catch(ZodSchemaDeclarationException)
export class ZodSchemaDeclarationExceptionFilter implements ExceptionFilter {
  catch(exception: ZodSchemaDeclarationException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    response.status(500).json({
      statusCode: 500,
      message: 'Missing nestjs-zod schema declaration',
    });
  }
}

Response Validation

ZodSerializerDto (Set zod DTO to serialize responses with)

function ZodSerializerDto(dto: ZodDto | UnknownSchema | [ZodDto] | [UnknownSchema])

Parses / serializes the return value of a controller method using the provided zod schema. This is especially useful to prevent accidental data leaks.

[!NOTE] Instead of ZodSerializerDto, consider using ZodResponse, which has some improvements over ZodSerializerDto

[!NOTE] For this feature to work, please ensure ZodSerializerInterceptor is setup correctly

Parameters

• options.dto - A ZodDto (or zod schema) to serialize the response with. If passed with array syntax ([MyDto]) then it will parse as an array. Note that the array syntax does not work with zod/mini, because it requires the schema have an .array() method

Example

const UserSchema = z.object({ username: string() })

class UserDto extends createZodDto(UserSchema) {}

@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @ZodSerializerDto(UserDto)
  getUser(id: number) {
    return this.userService.findOne(id)
  }
}

In the above example, if the userService.findOne method returns password, the password property will be stripped out thanks to the @ZodSerializerDto decorator.

Also note that arrays can be serialized using [] syntax like this:

class BookDto extends createZodDto(z.object({ title: string() })) {}

@Controller('books')
export class BooksController {
  constructor() {}

  @ZodSerializerDto([BookDto])
  getBooks() {
    return [{ title: 'The Martian' }, { title: 'Hail Marry' }];
  }
}

Or by using an array DTO:

class BookListDto extends createZodDto(z.array(z.object({ title: string() }))) {}

@Controller('books')
export class BooksController {
  constructor() {}

  @ZodSerializerDto(BookListDto)
  getBooks() {
    return [{ title: 'The Martian' }, { title: 'Hail Marry' }];
  }
}

ZodSerializerInterceptor (Get nestjs to serialize responses with zod)

To ensure ZodSerializerDto works correctly, ZodSerializerInterceptor needs to be added to the AppModule

[!NOTE] Also see ZodSerializationException for information about customizing the serialization error handling

Example

This should be done in the AppModule like so:

@Module({
  ...
  providers: [
    ...,
    { provide: APP_INTERCEPTOR, useClass: ZodSerializerInterceptor },
  ],
})
export class AppModule {}

createZodSerializerInterceptor (Creating custom serializer interceptor)

export function createZodSerializerInterceptor({ reportInput }: ZodSerializerInterceptorOptions = {}): ZodSerializerInterceptorClass

Creates a custom zod serializer interceptor

Parameters

• params.reportInput - When set to true, includes the input value in Zod error issues. This is useful for debugging serialization errors. Only supported in Zod v4.

Example

import { createZodSerializerInterceptor } from 'nestjs-zod'
import { APP_INTERCEPTOR } from '@nestjs/core'

const CustomZodSerializerInterceptor = createZodSerializerInterceptor({
  reportInput: true,
})

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: CustomZodSerializerInterceptor,
    },
  ],
})
export class AppModule {}

ZodResponse (Sync run-time, compile-time, and docs-time schemas)

function ZodResponse<TSchema extends UnknownSchema>({ status, description, type }: { status?: number, description?: string, type: ZodDto<TSchema> & { io: "input" } }): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => input<TSchema>|Promise<input<TSchema>>>, 'value'>) => void
function ZodResponse<TSchema extends RequiredBy<UnknownSchema, 'array'>>({ status, description, type }: { status?: number, description?: string, type: [ZodDto<TSchema> & { io: "input" }] }): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => Array<input<TSchema>>|Promise<Array<input<TSchema>>>>, 'value'>) => void

Consolidation of multiple decorators that allows setting the run-time, compile-time, and docs-time schema all at once

[!NOTE] For this feature to work, please ensure ZodSerializerInterceptor and cleanupOpenApiDoc are setup correctly

Parameters

• params.status - Optionally sets the "happy-path" status of the response. If provided, sets the status code using @HttpCode from nestjs/common and using @ApiResponse from nestjs/swagger
• params.description - Optionally sets a description of the response using @ApiResponse
• params.type - Sets the run-time (via @ZodSerializerDto), compile-time (via TypeScript), and docs-time (via @ApiResponse) response type.

Example

You may find yourself duplicating type information:

@ZodSerializer(BookDto)
@ApiOkResponse({
  status: 200,
  type: BookDto
})
getBook(): BookDto {
  ...
}

Here, BookDto is repeated 3 times:

1. To set the DTO to use to serialize
2. To set the DTO to use for the OpenAPI documentation
3. To set the return type for the function

If these 3 spots get out of sync, this may cause bugs. If you want to remove this duplication, you can consolidate using ZodResponse:

- @ZodSerializer(BookDto)
- @ApiOkResponse({
-  status: 200,
-  type: BookDto.Output
- })
- getBook(): BookDto {
+ @ZodResponse({ type: BookDto })
+ getBook()
  ...
}

@ZodResponse will set all these things. It will set the DTO to use to serialize, it will set the DTO to use for the OpenAPI documentation, and it will throw a compile-time typescript error if the method does not return data that matches the zod input schema

This is pretty powerful, because it ensures the run-time, compile-time, and docs-time representations of your response are all in sync. For this reason, it's recommended to use @ZodResponse instead of repeating the DTO three times.

ZodSerializationException

If the zod response serialization fails, then nestjs-zod will throw a ZodSerializationException, which will result in the following HTTP response:

{
  "message": "Internal Server Error",
  "statusCode": 500,
}

You can customize the exception and HTTP response handling ZodSerializationException inside an exception filter

See the example app here for more information.

OpenAPI (Swagger) support

[!NOTE] For additional documentation, follow Nest.js' Swagger Module Guide, or you can see the example application here

If you have @nestjs/swagger setup, documentation will automatically be generated for:

• Request bodies, if you use @Body() body: MyDto
• Response bodies, if you use @ApiOkResponse({ type: MyDto.Output }) (or @ZodResponse({ type: MyDto }))
• Query params, if you use @Query() query: MyQueryParamsDto

To generate the OpenAPI document, nestjs-zod uses z.toJSONSchema for zod v4 schemas. It's recommended to review the zod documentation itself for more information about how the OpenAPI document is generated

For zod v3 schemas, nestjs-zod uses a custom-built (deprecated) function called zodV3ToOpenAPI that generates the OpenAPI document by inspecting the zod schema directly.

However, please note cleanupOpenApiDoc is required to get the correct OpenAPI output, as shown below:

cleanupOpenApiDoc (Ensure proper OpenAPI output)

function cleanupOpenApiDoc(doc: OpenAPIObject, options?: { version?: '3.1' | '3.0' | 'auto' }): OpenAPIObject

Cleans up the generated OpenAPI doc by applying some post-processing and ensuring it complies with the optionally specified OpenAPI version

[!IMPORTANT] Using this function is required when using @nestjs/swagger to get the correct OpenAPI output!!

Parameters

• doc - The OpenAPI doc generated by SwaggerModule.createDocument
• options.version - The OpenAPI version to use while cleaning up the document.
  • auto (default) - Uses the version specified in the OpenAPI document (The version in the OpenAPI can be changed by using the setOpenAPIVersion method on the swagger document builder).
  • 3.1 - Generates schemas that take advantage of OpenAPI 3.1 syntax. See table below for more information
  • 3.0 - Generates schemas that are compatible with OpenAPI 3.0. See table below for more information

Example

To complete the swagger integration/setup, cleanupOpenApiDoc needs to be called with the generated open api doc, like so:

  const openApiDoc = SwaggerModule.createDocument(app, 
      new DocumentBuilder()
        .setTitle('Example API')
        .setDescription('Example API description')
        .setVersion('1.0')
        .build(),
  );
- SwaggerModule.setup('api', app, openApiDoc);
+ SwaggerModule.setup('api', app, cleanupOpenApiDoc(openApiDoc));

Output schemas

Note that z.toJSONSchema can generate two versions of any zod schema: "input" or "output". This is what the zod documentation says about this:

Some schema types have different input and output types, e.g. ZodPipe, ZodDefault, and coerced primitives.

Note that by default, when generating OpenAPI documentation, nestjs-zod uses the "input" version of a schema, except for @ZodResponse which always generates the "output" version of a schema. If you want to explicitly use the "output" version of a schema when generating OpenAPI documentation, you can use the .Output property of a zod DTO. For example, this makes sense when using @ApiResponse:

@ApiResponse({
  type: MyDto.Output
})

However, it's recommended to use @ZodResponse over @ApiResponse, which automatically handles this for you:

@ZodResponse({
  type: MyDto // <-- No need to do `.Output` here
})

Codecs

Zod 4.1 introduced a new feature called "codecs". There is more information about codecs in the zod documentation

nestjs-zod supports codecs. If the codec: true option is used when creating the zod DTO, then parse will be used for request bodies, and encode will be used when serializing response bodies.

codecs can enable, in some cases, using one zod schema, instead of two, for both the request and response

const stringToDate = z.codec(
  z.iso.datetime(),
  z.date(),
  {
    decode: (isoString) => new Date(isoString),
    encode: (date) => date.toISOString(),
  }
);

class BookDto extends createZodDto(z.object({
  title: z.string(),
  dateWritten: stringToDate
}), {
  codec: true
}) { }

@Controller('books')
class BookController {
  constructor() { }
  
  @Post()
  @ZodResponse({ 
    type: BookDto
  })
  createBook(@Body() book: BookDto) {
    return book;
  }
}

See the example app here for a full example.

Reusable schemas

You can also externalize and reuse schemas across multiple DTOs. If you add .meta({ id: "MySchema" }) to any zod schema, then that schema will be added directly to components.schemas in the OpenAPI documentation. For example, this code:

const Author = z.object({ name: z.string() }).meta({ id: "Author" })

class BookDto extends createZodDto(z.object({ title: z.string(), author: Author })) { }
class BlogPostDto extends createZodDto(z.object({ title: z.string(), author: Author })) { }

Will result in this OpenAPI document:

{
  "components": {
    "schemas": {
      "Author": {
        // ...
      },
      "BookDto": {
        "type": "object",
        "properties": {
          "author": {
            "$ref": "#/components/schemas/Author"
          },
          "required": ["author"]
        }
      },
      "BlogPostDto": {
        "type": "object",
        "properties": {
          "author": {
            "$ref": "#/components/schemas/Author"
          },
          "required": ["author"]
        }
      }
    }
  },
  // ...
}

Schema names

Note that schemas are named / displayed in SwaggerUI according to the following logic:

1. For input schemas, (e.g. schemas used in request bodies), SwaggerUI will display the id property in .meta({ id: 'MySchema' })
2. For output schemas, (e.g. schemas used in @ZodResponse()), nestjs-zod suffixes the id set by .meta({ id: 'MySchema' }) with _Output, so SwaggerUI displays, for example, MySchema_Output. This is important to avoid collision with input schemas.
3. However, if title is set by .meta({ title: ... }), then SwaggerUI will display title. Note that unlike ids, there is no duplicate checking for titles, so it's the consumer's responsibility to avoid confusion when using title.

zodV3ToOpenAPI (DEPRECATED)

[!CAUTION] zodV3ToOpenAPI is deprecated and will not be supported soon, since zod v4 adds built-in support for generating OpenAPI schemas from zod schemas. See MIGRATION.md for more information.

validate (DEPRECATED)

[!CAUTION] validate is deprecated and will not be supported soon. It is recommended to use .parse directly. See MIGRATION.md for more information.

ZodGuard (DEPRECATED)

[!CAUTION] Guard-related functions are deprecated and will not be supported soon. It is recommended to use guards for authorization, not validation. See MIGRATION.md for more information.

@nest-zod/z (DEPRECATED)

[!CAUTION] @nest-zod/z is no longer supported and has no impact on the OpenAPI generation. It is recommended to use zod directly. See MIGRATION.md for more information.

Credits

This library was originally created by risen228 and now maintained by BenLorantfy (that's me!)

I'm for hire! Check out my resume here. You can email me at ben@lorantfy.com if you want to chat.