Add Standard Schema validation support for configuration schema #2122

iamnivekx · 2025-07-23T01:49:40Z

PR Checklist

Please check if your PR fulfills the following requirements:

The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

What is the current behavior?

Issue Number:
#1164

What is the new behavior?

Does this PR introduce a breaking change?

Yes
No

Other information

micalevisk · 2025-07-27T18:37:33Z

I like the ideia of supporting zod specially now with a lot of AI-related stuff using it. Can you elaborate a bit on why we can't use zod prior to this PR? I thought that we're able to use zod alreay in @nestjs/config v4.0.2 🤔

iamnivekx · 2025-07-28T02:01:09Z

You're absolutely right — technically, Zod can be used with @nestjs/[email protected] via a custom validate function.

The main goals of this PR are:

To provide first-class support for Zod, allowing developers to pass Zod schemas directly into the config module, just like with Joi;
To improve developer experience (DX) by removing the need for custom integration logic or adapters.

nstandif · 2025-08-23T19:18:37Z

package.json

    "typescript": "5.8.3",
-    "typescript-eslint": "8.38.0"
+    "typescript-eslint": "8.38.0",
+    "zod": "^4.0.5"


Adding zod like this is going to break others as libraries have been slow to adopt zod v4. See https://zod.dev/library-authors#how-to-support-zod-4

I still think "zod": "^3.25.0 || ^4.0.0" should be added as a peer dependency, so that npm can manage this. Also, please consider `"joi": "^17.13.0 || ^18.0.0" added as a peer dep., granted that you have tested 'joi v18' and we don't have node 12 compatibility to maintain for this library.

nstandif · 2025-08-23T19:22:34Z

lib/validators/validator.factory.ts

@@ -0,0 +1,67 @@
+import { type Schema as JoiSchema } from 'joi';
+import { type ZodType } from 'zod';


Please use zod/v3 zod/v4/core, respectively. Using zod this way will cause both zod v3 and zod v4 mini to break when using this library.

nstandif · 2025-08-23T19:23:43Z

tests/src/app.module.ts

@@ -1,5 +1,6 @@
 import { DynamicModule, Inject, Module, Optional } from '@nestjs/common';
 import Joi from 'joi';
+import { z } from 'zod';


Tests should be done across v3, v4, and v4 mini, as they are all supported versions of Zod.

nstandif · 2025-08-23T19:24:48Z

lib/validators/zod.validator.ts

@@ -0,0 +1,39 @@
+import type { ZodType } from 'zod';


nstandif · 2025-08-23T19:25:00Z

lib/validators/validator.factory.ts

+      'parse' in schema &&
+      typeof schema.parse === 'function'
+    ) {
+      return this.createZodValidator(schema as ZodType);


nstandif · 2025-08-23T19:28:20Z

lib/validators/validator.factory.ts

+   * @param schema Joi schema
+   * @returns JoiValidator instance
+   */
+  static createJoiValidator(schema: JoiSchema): Validator {


why not put these factory methods in validators themselves?

nstandif · 2025-08-23T19:33:23Z

lib/validators/validator.factory.ts

+    if (
+      schema &&
+      typeof schema === 'object' &&
+      'validate' in schema &&
+      typeof schema.validate === 'function'
+    ) {
+      return this.createJoiValidator(schema as JoiSchema);
+    }
+
+    // Check if it's a Zod schema
+    if (
+      schema &&
+      typeof schema === 'object' &&
+      'parse' in schema &&
+      typeof schema.parse === 'function'
+    ) {
+      return this.createZodValidator(schema as ZodType);


Instead of forcing this check on the user each time, why not use some dependency injection on the factory itself? It's highly unlikely that there would be two different types of validation schemas in the same class or even module. You could use this logic to validate against once instead of each time the createValidator is called.

iamnivekx · 2025-08-24T14:20:37Z

@nstandif

Thanks for the suggestion!

Your dependency injection approach makes sense, but createValidator is only called once during module init, making the type detection overhead negligible.
Regarding Zod not being added to peerDependencies: I followed the same pattern as Joi - both are optional validation libraries that users can choose to install based on their needs. This keeps the core package lightweight and avoids forcing users to install validation libraries they don't use.
I've also added comprehensive test coverage for all three Zod versions (v3, v4, and v4 mini) to ensure the implementation works correctly across different versions.

nstandif

Maybe we could do a StandardSchemaV1 validator instead of just zod? I don't see anything that is implementation specific to zod that we'd need to support. WDYT?

nstandif · 2025-08-28T16:25:00Z

lib/types/zod.type.ts

@@ -0,0 +1,7 @@
+import type { ZodType as ZodTypeV3 } from 'zod/v3';
+import type { ZodType as ZodTypeV4 } from 'zod/v4';


Should use $ZodType from zod/v4/core.

All Zod Mini schemas extend the z.ZodMiniType base class, which in turn extends z.core.$ZodType from zod/v4/core. While this class implements far fewer methods than ZodType in zod, some particularly useful methods remain.

Zod Mini | Zod

nstandif · 2025-08-28T16:41:17Z

package.json

    "typescript": "5.8.3",
-    "typescript-eslint": "8.38.0"
+    "typescript-eslint": "8.38.0",
+    "zod": "^4.0.5"


I still think "zod": "^3.25.0 || ^4.0.0" should be added as a peer dependency, so that npm can manage this. Also, please consider `"joi": "^17.13.0 || ^18.0.0" added as a peer dep., granted that you have tested 'joi v18' and we don't have node 12 compatibility to maintain for this library.

iamnivekx · 2025-09-01T10:00:52Z

Maybe we could do a StandardSchemaV1 validator instead of just zod? I don't see anything that is implementation specific to zod that we'd need to support. WDYT?

Good point — I agree, there doesn’t seem to be anything strictly tied to Zod here. Supporting StandardSchemaV1 sounds like a better approach.

iamnivekx · 2025-09-01T10:10:32Z

I still think "zod": "^3.25.0 || ^4.0.0" should be added as a peer dependency, so that npm can manage this. Also, please consider `"joi": "^17.13.0 || ^18.0.0" added as a peer dep., granted that you have tested 'joi v18' and we don't have node 12 compatibility to maintain for this library.

I see your point, but since these dependencies are optional, I think it’s clearer and simpler to keep them out of peerDependencies. This way we avoid forcing consumers to install packages they may not need.

iamnivekx · 2025-09-01T10:11:20Z

Maybe we could do a StandardSchemaV1 validator instead of just zod? I don't see anything that is implementation specific to zod that we'd need to support. WDYT?

Good point — I agree, there doesn’t seem to be anything strictly tied to Zod here. Supporting StandardSchemaV1 sounds like a better approach.

@nstandif DONE!

nstandif

LGTM

nstandif · 2025-09-01T14:40:38Z

Once you get this merged in, please make a PR to nestjs/docs.nestjs.com and standard-schema/standard-schema so that others know that standard schema is supported!

iamnivekx · 2025-09-02T01:37:27Z

Got it — I’m waiting for the merge.
@micalevisk do you think there’s a chance this could be merged?

micalevisk · 2025-09-02T01:38:59Z

I hope so

… Zod v3 and v4 - Added a new type definition for ZodType that supports both Zod v3 and v4. - Refactored validator imports to use the new ZodType definition. - Updated AppModule to include methods for Zod v3, v4, and v4 mini schema validation. - Enhanced e2e tests to validate environment variables using the new Zod schema methods.

…tions parameter

…ator comments

…lidatorFactory

iamnivekx · 2025-09-02T04:39:36Z

joi also supports Standard Schema. hapijs/joi#3080

nstandif · 2025-09-03T05:33:05Z

joi also supports Standard Schema. hapijs/joi#3080

Yes, but it is only supported as of v18.0.0+. Removing the joi dependency would be breaking.

iamnivekx · 2025-09-03T05:50:55Z

Yes, just pointing it out here — I don’t want to introduce major changes either, but thought it might be helpful to mention. Thanks!

iamnivekx mentioned this pull request Jul 24, 2025

Add support for Zod in schema validation #1164

Closed

1 task

iamnivekx force-pushed the feature/extend-schema branch from c266d8d to 22298fe Compare July 30, 2025 02:12

nstandif reviewed Aug 23, 2025

View reviewed changes

lib/validators/zod.validator.ts Outdated

@@ -0,0 +1,39 @@

import type { ZodType } from 'zod';

Copy link

nstandif Aug 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto.

nstandif reviewed Aug 23, 2025

View reviewed changes

iamnivekx requested a review from nstandif August 24, 2025 14:20

nstandif reviewed Aug 28, 2025

View reviewed changes

iamnivekx requested a review from nstandif September 1, 2025 10:11

nstandif approved these changes Sep 1, 2025

View reviewed changes

iamnivekx changed the title ~~feat: add Zod validation support for configuration schema~~ Add Standard Schema validation support for configuration schema Sep 2, 2025

iamnivekx added 4 commits September 2, 2025 09:56

feat: add Zod validation support for configuration schema

dab84cf

feat: integrate Standard Schema validation

dbe454d

refactor: simplify StandardValidator constructor and remove unused op…

214f44b

…tions parameter

iamnivekx force-pushed the feature/extend-schema branch from 8ede4e9 to 214f44b Compare September 2, 2025 02:07

iamnivekx added 2 commits September 2, 2025 10:16

refactor: update validation schema documentation and improve JoiValid…

5dbb732

…ator comments

refactor: enhance validation logic and improve schema detection in Va…

3cd96b3

…lidatorFactory

		@@ -0,0 +1,67 @@
		import { type Schema as JoiSchema } from 'joi';
		import { type ZodType } from 'zod';

		@@ -0,0 +1,7 @@
		import type { ZodType as ZodTypeV3 } from 'zod/v3';
		import type { ZodType as ZodTypeV4 } from 'zod/v4';

Add Standard Schema validation support for configuration schema #2122

Are you sure you want to change the base?

Add Standard Schema validation support for configuration schema #2122

Uh oh!

Conversation

iamnivekx commented Jul 23, 2025

PR Checklist

PR Type

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change?

Other information

Uh oh!

micalevisk commented Jul 27, 2025

Uh oh!

iamnivekx commented Jul 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iamnivekx commented Aug 24, 2025

Uh oh!

nstandif left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iamnivekx commented Sep 1, 2025

Uh oh!

iamnivekx commented Sep 1, 2025

Uh oh!

iamnivekx commented Sep 1, 2025

Uh oh!

nstandif left a comment

Choose a reason for hiding this comment

Uh oh!

nstandif commented Sep 1, 2025

Uh oh!

iamnivekx commented Sep 2, 2025

Uh oh!

micalevisk commented Sep 2, 2025

Uh oh!

iamnivekx commented Sep 2, 2025

Uh oh!

nstandif commented Sep 3, 2025

Uh oh!

iamnivekx commented Sep 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants