V5 beta (including zod/v4 support)

[BenLorantfy]

Hi everyone,

I wanted to announce that I've published the v5 beta. You can install it using the next tag:

npm install nestjs-zod@next

v5 is planning on including several updates, including:

1. Adding support for zod/v4, which was released stable today (May 19th, 2025)
2. Streamlining the api surface by removing or deprecating several extraneous or redundant apis, including:
   i. Removing patchNestJsSwagger
   ii. Deprecating validate (redundant with parse), UseZodGuard / ZodGuard (not recommended for validation by nestjs), zodToOpenAPI (redundant with z.toJsonSchema), etc.
3. Reusable / shared openapi components (see Reusable schema defs #147 and OpenAPI shared components #137)
4. Fixing misc bugs or odd behaviour that may require some breaking changes
5. Implementing some of the ideas from the nestjs author here

Please feel free to try it out today and let me know in the comments if you run into any issues (especially if you try it out with zod/v4 on a medium / large codebase). But please note that some changes are likely in the coming days so it's not recommended for production use.

You can also follow me on twitter if you want more updates: https://x.com/benlorantfy

Cheers,
Ben

[Olyve]

Working on a project that would benefit from upgrading to Zod v4, we use nestjs-zod pretty heavily, so definitely keeping an eye on this getting merged to main! 🥳

[shawnmcknight]

@BenLorantfy Thanks for your work with this project. I'm trialing the beta today alongside zod 3.25.32 and noticed that I was getting peer dependency warnings for zod. Looking at the v5 dependency list I see that it is pinned to 3.25.3. Is this pinning intentional or is there a missing version range qualifier (caret or otherwise)?

Thanks!

[BenLorantfy]

@shawnmcknight this should be fixed in the latest beta version

[ShahriarKh]

I tried to use the beta version but got this error:

TypeError: Cannot convert undefined or null to object
    at Function.keys (<anonymous>)
    at ModelPropertiesAccessor.applyMetadataFactory (D:\***\***\node_modules\@nestjs\swagger\dist\services\model-properties-accessor.js:28:39)
    at SchemaObjectFactory.extractPropertiesFromType (D:\***\***\node_modules\@nestjs\swagger\dist\services\schema-object-factory.js:130:38)
    at SchemaObjectFactory.exploreModelSchema (D:\***\***\node_modules\@nestjs\swagger\dist\services\schema-object-factory.js:157:41)
    at ResponseObjectFactory.create (D:\***\***\node_modules\@nestjs\swagger\dist\services\response-object-factory.js:49:47)
    at D:\***\***\node_modules\@nestjs\swagger\dist\explorers\api-response.explorer.js:76:101
    at D:\***\***\node_modules\lodash\lodash.js:13469:38
    at D:\***\***\node_modules\lodash\lodash.js:4967:15
    at baseForOwn (D:\***\***\node_modules\lodash\lodash.js:3032:24)
    at mapValues (D:\***\***\node_modules\lodash\lodash.js:13468:7)

I assumed it was due to being on nest 10, but upgrading to nest 11 didn't help.

const options = new DocumentBuilder().build()
const document = SwaggerModule.createDocument(app, options); // this is the line that throws an error

related packages in my project:

"@nestjs/core": "^11.1.3",
"@nestjs/swagger": "^11.2.0",
"nestjs-zod": "^5.0.0-beta.20250519T201559",
"zod": "^3.25.3"

[BenLorantfy]

@ShahriarKh please feel free to try on the latest beta version and lmk if you still have this issue

[jaenster]

Is it hard to backport the zod4 migration? As for the openapi specification generation, the "example" values are really missing, and with zod4 we can have this with ease.

I really love the package but i have to admit, i have really considered stop using it right now, as the openapi generation is a bit limited (which all will be fixed with zod4). I have some time where i can wait for the zod4 version with e.g. example fields in the openapi spec.

Also happy to help by the way, if you tell me what i can do from my end to have it

[BenLorantfy]

@jaenster I don't plan on backporting zod v4 support due to the maintenance burden. I don't expect significant breaking changes in v5, so it shouldn't require much effort to migrate.

[jaenster]

@BenLorantfy I understand! What is the time line of version 5 coming out? It also solves another issue we have. Is it coming the following next weeks? Great project btw!

[BenLorantfy]

It should be out soon (next week or so)

[BenLorantfy]

Another beta version of nestjs-zod has been published that includes support for external / reusable schemas: nestjs-zod@5.0.0-beta.20250719T005107

Please feel free to try it out and let me know if you have any problems / feedback 🙏

[rodrigowbazevedo]

I just tested and it's working fine for me!

[Fuzznimp]

Just bumped to 5.0.0-beta.20250719T005107.
Works like a charm! We can finally ditch class-validator and use nestjs-zod for query strings 🎉.
Thanks for you work 🙏 .

[stephane-ruhlmann]

Just updated to 5.0.0-beta.20250719T005107 and it works 👍

[mahendraHegde]

Does anyone know why cant i get intellisense with the DTO instances? everything is any

export class CreateUserDto extends createZodDto(createUserSchema) {}
  async createUser(
    @Body() createUserDto: CreateUserDto
  ): Promise<UserResponseDto> {
    createUserDto.email
    return this.userService.syncUser(createUserDto);
  }

[3N14C]

But.....

-- FIXED --
Oh great i solved this problem
My schema:

And my dto:

Just use 'nestjs-zod/dto'. Just use this and get rid of any type problems

[BenLorantfy]

Hey folks, the last-ish beta version I plan to release is nestjs-zod@5.0.0-beta.20250812T233646

If you'd like to try it out, please feel free to lmk if you have any feedback (including on the README.md and MIGRATION.md pages)

If all goes well I plan to release v5 this Thursday, August 14th Monday, August 18th

[gabriel-jolly]

🙌

[AmazingTurtle]

There were still refs to $defs/_schema0.

export const variablesSchemaSchema = z.object({
  properties: z.record(z.string(), z.any()).optional(),
  required: z.array(z.string()).optional(),
});

this works, but:

export const variablesSchemaSchema = z.object({
  properties: z.record(z.string(), jsonSchema4Schema).optional(),
  required: z.array(z.string()).optional(),
});

this doesn't.

jsonSchema4Schema here:

export const jsonSchema4Schema: z.ZodType<JSONSchema4> = z.lazy(
  () =>
    z
      .object({
        id: z.string().optional(),
        $schema: z.string().optional(),
        title: z.string().optional(),
        description: z.string().optional(),
        default: z.any().optional(),

        // Numeric validators
        multipleOf: z.number().positive().optional(),
        maximum: z.number().optional(),
        exclusiveMaximum: z.boolean().optional(),
        minimum: z.number().optional(),
        exclusiveMinimum: z.boolean().optional(),

        // String validators
        maxLength: z.number().int().nonnegative().optional(),
        minLength: z.number().int().nonnegative().optional(),
        pattern: z.string().optional(),
        format: z.string().optional(),

        // Array validators
        additionalItems: z.union([z.boolean(), jsonSchema4Schema]).optional(),
        items: z
          .union([jsonSchema4Schema, z.array(jsonSchema4Schema)])
          .optional(),
        maxItems: z.number().int().nonnegative().optional(),
        minItems: z.number().int().nonnegative().optional(),
        uniqueItems: z.boolean().optional(),

        // Object validators
        maxProperties: z.number().int().nonnegative().optional(),
        minProperties: z.number().int().nonnegative().optional(),
        required: z.array(z.string()).optional(),
        additionalProperties: z
          .union([z.boolean(), jsonSchema4Schema])
          .optional(),
        definitions: z.record(z.string(), jsonSchema4Schema).optional(),
        properties: z.record(z.string(), jsonSchema4Schema).optional(),
        patternProperties: z.record(z.string(), jsonSchema4Schema).optional(),
        dependencies: z
          .record(z.string(), z.union([jsonSchema4Schema, z.array(z.string())]))
          .optional(),

        // Generic validators
        enum: z.array(z.any()).optional(),
        type: z
          .union([
            z.enum([
              'string',
              'number',
              'integer',
              'object',
              'array',
              'boolean',
              'null',
            ]),
            z.array(
              z.enum([
                'string',
                'number',
                'integer',
                'object',
                'array',
                'boolean',
                'null',
              ]),
            ),
          ])
          .optional(),

        // Applicators
        allOf: z.array(jsonSchema4Schema).optional(),
        anyOf: z.array(jsonSchema4Schema).optional(),
        oneOf: z.array(jsonSchema4Schema).optional(),
        not: jsonSchema4Schema.optional(),
      })
      .and(z.record(z.string(), z.any())), // Allows for custom/non-standard keywords
);```

[BenLorantfy]

@AmazingTurtle This should be fixed in 5.0.0-beta.20250819T005332

[AmazingTurtle]

Error during application bootstrap: Error: [nestjs-zod] createZodDto must be called with an object type
    at assert (C:\myrepo\node_modules\nestjs-zod\dist\index.js:19:11)
    at openApiMetadataFactory (C:\myrepo\node_modules\nestjs-zod\dist\index.js:386:3)
    at GetMeContextResponseModel._OPENAPI_METADATA_FACTORY (C:\myrepo\node_modules\nestjs-zod\dist\index.js:358:14)
    at ModelPropertiesAccessor.applyMetadataFactory (C:\myrepo\node_modules\@nestjs\swagger\dist\services\model-properties-accessor.js:27:93)
    at SchemaObjectFactory.extractPropertiesFromType (C:\myrepo\node_modules\@nestjs\swagger\dist\services\schema-object-factory.js:112:38)
    at SchemaObjectFactory.exploreModelSchema (C:\myrepo\node_modules\@nestjs\swagger\dist\services\schema-object-factory.js:139:41)
    at ResponseObjectFactory.create (C:\myrepo\node_modules\@nestjs\swagger\dist\services\response-object-factory.js:49:47)
    at C:\myrepo\node_modules\@nestjs\swagger\dist\explorers\api-response.explorer.js:67:101
    at C:\myrepo\node_modules\lodash\lodash.js:13469:38
    at C:\myrepo\node_modules\lodash\lodash.js:4967:15

Now that I am migrating already, I found that these error messages are quite confusing, as I have over > 100 zod DTOs and I don't know which of them causes issues;

I figured that this was caused by an z.intersection() type!

Additionally, ( I don't want to open a new comment ) I learned that:

"name": {
	"type": "string",
	"nullable": true
}

becomes

"name": {
	"anyOf": [
		{
			"type": "string"
		},
		{
			"type": "null"
		}
	]
}

[BenLorantfy]

@AmazingTurtle Intersections should be fixed in nestjs-zod@5.0.0-beta.20250819T002329

Regarding null;

1. In openapi version 3.0, nullable is expressed as "nullable": true
2. In openapi version 3.1, nullable is expressed using anyOf and { type: 'null' }

There's more information about this if you look at the documentation for options.version here: https://github.com/BenLorantfy/nestjs-zod/tree/v5?tab=readme-ov-file#cleanupopenapidoc-ensure-proper-openapi-output

[mallowigi]

Re @BenLorantfy

I still have an issue with the migration. In the md file you said that

Deprecated validate
validate was a redudant and confusingly named function (it should have been called parse if we wanted to keep it). You can simply use the .parse function that is attached to the zod schema

But when I ran the program, I get the following stacktrace:

ZodSerializationException: Internal Server Error
    at createZodSerializationException (/Users/e137006/projects/smarts-adapter/node_modules/nestjs-zod/dist/index.js:505:10)
    at validate (/Users/e137006/projects/smarts-adapter/node_modules/nestjs-zod/dist/index.js:513:11)
    at /Users/e137006/projects/smarts-adapter/node_modules/nestjs-zod/dist/index.js:626:16
...

This is from a controller annotated as follows:

@ZodSerializerDto(GetSmartResponseDto)
  async get(@Param('id') id: number, @Headers() headers: Record<string, string>): Promise<GetSmartResponseDto> {
...
}

[BenLorantfy]

Hey @mallowigi , couple questions here:

1. I don't understand why validate is relevant, since validate is not present in the snippet you shared
2. It's expected behaviour to get a ZodSerializationException when the controller method returns data that doesn't match the DTO. Is that what's happening here? You didn't share the implementation of get, nor GetSmartResponseDto, nor any logs of what data is being returned at runtime.

[mallowigi]

@BenLorantfy I was under the assumption that it was still using validate as you can see from the stack trace.

I can't share the source code but in short, I have added the following exception filter

@Catch(HttpException)
export class ZodHttpExceptionFilter extends BaseExceptionFilter {
  private readonly logger = new Logger(ZodHttpExceptionFilter.name);

  catch(exception: HttpException, host: ArgumentsHost) {
    if (exception instanceof ZodSerializationException) {
      const zodError = exception.getZodError();
      if (zodError instanceof ZodErrorV3) {
        this.logger.error(`ZodSerializationException: ${zodError.message}`);
      } else if (zodError instanceof ZodErrorV4) {
        this.logger.error(`ZodSerializationException: ${zodError.message}`);
      }
    }

    super.catch(exception, host);
  }
}

When I debug, the problem comes from the zodError, which gives me the following stack trace:

TypeError: zod.defaultErrorMap is not a function
    at Object.extendedErrorMap [as customError] (/Users/e137006/projects/smarts-adapter/node_modules/@nest-zod/z/dist/z.js:178:14)
    at Object.finalizeIssue (/Users/e137006/projects/smarts-adapter/node_modules/zod/v4/core/util.cjs:533:47)
    at /Users/e137006/projects/smarts-adapter/node_modules/zod/v4/core/parse.cjs:37:78
    at Array.map (<anonymous>)
    at Object.parse (/Users/e137006/projects/smarts-adapter/node_modules/zod/v4/core/parse.cjs:37:60)
    at inst.parse (/Users/e137006/projects/smarts-adapter/node_modules/zod/v4/classic/schemas.cjs:138:42)
    at validate (/Users/e137006/projects/smarts-adapter/node_modules/nestjs-zod/dist/index.js:511:19)
    at /Users/e137006/projects/smarts-adapter/node_modules/nestjs-zod/dist/index.js:626:16
    at <anonymous> (/Users/e137006/projects/smarts-adapter/node_modules/rxjs/src/internal/operators/map.ts:57:33)
    at OperatorSubscriber.OperatorSubscriber._this._next (/Users/e137006/projects/smarts-adapter/node_modules/rxjs/src/internal/operators/OperatorSubscriber.ts:70:13)

[BenLorantfy]

This is a new error right? You provided a different stack trace from the one in the original comment

I don't think I'll be able to help here unless you can provide a minimal reproducible example. Please feel free to open a bug if you have a minimal reproducible example

Btw the stack trace implies you're using @nest-zod/z. That library has been deprecated and unsupported for almost a year and has no effect in nestjs-zod v5. You could try changing to zod directly and see if that helps

[mallowigi]

The previous stack trace was what I received from the response whereas this stack trace is taken after stopping at the breakpoint of the exception filter.

I'll try to see if I can spruce up an example repository with a trimmed version of the project. I'll also check for the z. It's very strange because as far as I remember I have been using the Zod library directly but who knows, maybe there was an import somewhere that I missed. Will update

[BenLorantfy]

v5 is out!

Release notes: https://github.com/BenLorantfy/nestjs-zod/releases/tag/v5.0.0
Migration guide: https://github.com/BenLorantfy/nestjs-zod/blob/main/MIGRATION.md