zod 4.1.2 → 4.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "type": "module",
   "license": "MIT",
   "author": "Colin McDonnell <zod@colinhacks.com>",

package/src/v4/classic/tests/to-json-schema.test.ts

@@ -1,7 +1,34 @@
+import { Validator } from "@seriousme/openapi-schema-validator";
 import { describe, expect, test } from "vitest";
 import * as z from "zod/v4";
 // import * as zCore from "zod/v4/core";
 
+const openAPI30Validator = new Validator();
+/** @see https://github.com/colinhacks/zod/issues/5147 */
+const validateOpenAPI30Schema = async (zodJSONSchema: Record<string, unknown>): Promise<true> => {
+  const res = await openAPI30Validator.validate({
+    openapi: "3.0.0",
+    info: {
+      title: "SampleApi",
+      description: "Sample backend service",
+      version: "1.0.0",
+    },
+    components: { schemas: { test: zodJSONSchema } },
+    paths: {},
+  });
+
+  if (!res.valid) {
+    // `console.error` should make `vitest` trow an unhandled error
+    // printing the validation messages in consoles
+    console.error(
+      `OpenAPI schema is not valid against ${openAPI30Validator.version}`,
+      JSON.stringify(res.errors, null, 2)
+    );
+  }
+
+  return true;
+};
+
 describe("toJSONSchema", () => {
   test("primitive types", () => {
     expect(z.toJSONSchema(z.string())).toMatchInlineSnapshot(`
@@ -552,8 +579,11 @@ describe("toJSONSchema", () => {
     `);
   });
 
-  test("nullable openapi", () => {
-    expect(z.toJSONSchema(z.string().nullable(), { target: "openapi-3.0" })).toMatchInlineSnapshot(`
+  test("nullable openapi-3.0", () => {
+    const schema = z.string().nullable();
+    const jsonSchema = z.toJSONSchema(schema, { target: "openapi-3.0" });
+    validateOpenAPI30Schema(jsonSchema);
+    expect(jsonSchema).toMatchInlineSnapshot(`
       {
         "nullable": true,
         "type": "string",
@@ -561,12 +591,39 @@ describe("toJSONSchema", () => {
     `);
   });
 
-  test("union with null openapi", () => {
+  test("union with null openapi-3.0", () => {
     const schema = z.union([z.string(), z.null()]);
-    expect(z.toJSONSchema(schema, { target: "openapi-3.0" })).toMatchInlineSnapshot(`
+    const jsonSchema = z.toJSONSchema(schema, { target: "openapi-3.0" });
+    validateOpenAPI30Schema(jsonSchema);
+    expect(jsonSchema).toMatchInlineSnapshot(`
       {
-        "nullable": true,
-        "type": "string",
+        "anyOf": [
+          {
+            "type": "string",
+          },
+          {
+            "enum": [
+              null,
+            ],
+            "nullable": true,
+            "type": "string",
+          },
+        ],
+      }
+    `);
+  });
+
+  test("number with exclusive min-max openapi-3.0", () => {
+    const schema = z.number().lt(100).gt(1);
+    const jsonSchema = z.toJSONSchema(schema, { target: "openapi-3.0" });
+    validateOpenAPI30Schema(jsonSchema);
+    expect(jsonSchema).toMatchInlineSnapshot(`
+      {
+        "exclusiveMaximum": true,
+        "exclusiveMinimum": true,
+        "maximum": 100,
+        "minimum": 1,
+        "type": "number",
       }
     `);
   });
@@ -652,6 +709,20 @@ describe("toJSONSchema", () => {
     `);
   });
 
+  test("record openapi-3.0", () => {
+    const schema = z.record(z.string(), z.boolean());
+    const jsonSchema = z.toJSONSchema(schema, { target: "openapi-3.0" });
+    validateOpenAPI30Schema(jsonSchema);
+    expect(jsonSchema).toMatchInlineSnapshot(`
+      {
+        "additionalProperties": {
+          "type": "boolean",
+        },
+        "type": "object",
+      }
+    `);
+  });
+
   test("tuple", () => {
     const schema = z.tuple([z.string(), z.number()]);
     expect(z.toJSONSchema(schema)).toMatchInlineSnapshot(`
@@ -691,10 +762,89 @@ describe("toJSONSchema", () => {
     `);
   });
 
-  test("tuple openapi", () => {
+  test("tuple openapi-3.0", () => {
+    const schema = z.tuple([z.string(), z.number()]);
+    const jsonSchema = z.toJSONSchema(schema, { target: "openapi-3.0" });
+    validateOpenAPI30Schema(jsonSchema);
+    expect(jsonSchema).toMatchInlineSnapshot(`
+      {
+        "items": {
+          "anyOf": [
+            {
+              "type": "string",
+            },
+            {
+              "type": "number",
+            },
+          ],
+        },
+        "maxItems": 2,
+        "minItems": 2,
+        "type": "array",
+      }
+    `);
+  });
+
+  test("tuple with rest openapi-3.0", () => {
+    const schema = z.tuple([z.string(), z.number()]).rest(z.boolean());
+    const jsonSchema = z.toJSONSchema(schema, { target: "openapi-3.0" });
+    validateOpenAPI30Schema(jsonSchema);
+    expect(jsonSchema).toMatchInlineSnapshot(`
+      {
+        "items": {
+          "anyOf": [
+            {
+              "type": "string",
+            },
+            {
+              "type": "number",
+            },
+            {
+              "type": "boolean",
+            },
+          ],
+        },
+        "minItems": 3,
+        "type": "array",
+      }
+    `);
+  });
+
+  test("tuple with null openapi-3.0", () => {
+    const schema = z.tuple([z.string(), z.number(), z.null()]);
+    const jsonSchema = z.toJSONSchema(schema, { target: "openapi-3.0" });
+    validateOpenAPI30Schema(jsonSchema);
+    expect(jsonSchema).toMatchInlineSnapshot(`
+      {
+        "items": {
+          "anyOf": [
+            {
+              "type": "string",
+            },
+            {
+              "type": "number",
+            },
+            {
+              "enum": [
+                null,
+              ],
+              "nullable": true,
+              "type": "string",
+            },
+          ],
+        },
+        "maxItems": 3,
+        "minItems": 3,
+        "type": "array",
+      }
+    `);
+  });
+
+  test("tuple draft-7", () => {
     const schema = z.tuple([z.string(), z.number()]);
-    expect(z.toJSONSchema(schema, { target: "openapi-3.0" })).toMatchInlineSnapshot(`
+    expect(z.toJSONSchema(schema, { target: "draft-7", io: "input" })).toMatchInlineSnapshot(`
       {
+        "$schema": "http://json-schema.org/draft-07/schema#",
         "items": [
           {
             "type": "string",
@@ -703,17 +853,19 @@ describe("toJSONSchema", () => {
             "type": "number",
           },
         ],
-        "maxItems": 2,
-        "minItems": 2,
         "type": "array",
       }
     `);
   });
 
-  test("tuple with rest openapi", () => {
+  test("tuple with rest draft-7", () => {
     const schema = z.tuple([z.string(), z.number()]).rest(z.boolean());
-    expect(z.toJSONSchema(schema, { target: "openapi-3.0" })).toMatchInlineSnapshot(`
+    expect(z.toJSONSchema(schema, { target: "draft-7", io: "input" })).toMatchInlineSnapshot(`
       {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "additionalItems": {
+          "type": "boolean",
+        },
         "items": [
           {
             "type": "string",
@@ -721,14 +873,60 @@ describe("toJSONSchema", () => {
           {
             "type": "number",
           },
+        ],
+        "type": "array",
+      }
+    `);
+  });
+
+  test("tuple with rest draft-7 - issue #5151 regression test", () => {
+    // This test addresses issue #5151: tuple with rest elements and ids
+    // in draft-7 had incorrect internal path handling affecting complex scenarios
+    const primarySchema = z.string().meta({ id: "primary" });
+    const restSchema = z.number().meta({ id: "rest" });
+    const testSchema = z.tuple([primarySchema], restSchema);
+
+    // Test both final output structure AND internal path handling
+    const capturedPaths: string[] = [];
+    const result = z.toJSONSchema(testSchema, {
+      target: "draft-7",
+      override: (ctx) => capturedPaths.push(ctx.path.join("/")),
+    });
+
+    // Verify correct draft-7 structure with metadata extraction
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "additionalItems": {
+          "$ref": "#/definitions/rest",
+        },
+        "definitions": {
+          "primary": {
+            "id": "primary",
+            "type": "string",
+          },
+          "rest": {
+            "id": "rest",
+            "type": "number",
+          },
+        },
+        "items": [
           {
-            "type": "boolean",
+            "$ref": "#/definitions/primary",
           },
         ],
-        "minItems": 2,
         "type": "array",
       }
     `);
+
+    // Verify internal paths are correct (this was the actual bug)
+    expect(capturedPaths).toContain("items/0"); // prefix items should use "items" path
+    expect(capturedPaths).toContain("additionalItems"); // rest should use "additionalItems" path
+    expect(capturedPaths).not.toContain("prefixItems/0"); // should not use draft-2020-12 paths
+
+    // Structural validations
+    expect(Array.isArray(result.items)).toBe(true);
+    expect(result.additionalItems).toBeDefined();
   });
 
   test("promise", () => {
@@ -1554,7 +1752,9 @@ test("unrepresentable literal values are ignored", () => {
     }
   `);
 
-  const b = z.z.toJSONSchema(z.literal([undefined, null, 5, BigInt(1324)]), { unrepresentable: "any" });
+  const b = z.z.toJSONSchema(z.literal([undefined, null, 5, BigInt(1324)]), {
+    unrepresentable: "any",
+  });
   expect(b).toMatchInlineSnapshot(`
     {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -1566,7 +1766,9 @@ test("unrepresentable literal values are ignored", () => {
     }
   `);
 
-  const c = z.z.toJSONSchema(z.literal([undefined]), { unrepresentable: "any" });
+  const c = z.z.toJSONSchema(z.literal([undefined]), {
+    unrepresentable: "any",
+  });
   expect(c).toMatchInlineSnapshot(`
     {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -1849,7 +2051,9 @@ test("basic registry", () => {
   myRegistry.add(User, { id: "User" });
   myRegistry.add(Post, { id: "Post" });
 
-  const result = z.z.toJSONSchema(myRegistry, { uri: (id) => `https://example.com/${id}.json` });
+  const result = z.z.toJSONSchema(myRegistry, {
+    uri: (id) => `https://example.com/${id}.json`,
+  });
   expect(result).toMatchInlineSnapshot(`
     {
       "schemas": {

package/src/v4/core/to-json-schema.ts

@@ -183,7 +183,7 @@ export class JSONSchemaGenerator {
             else json.type = "number";
 
             if (typeof exclusiveMinimum === "number") {
-              if (this.target === "draft-4") {
+              if (this.target === "draft-4" || this.target === "openapi-3.0") {
                 json.minimum = exclusiveMinimum;
                 json.exclusiveMinimum = true;
               } else {
@@ -199,7 +199,7 @@ export class JSONSchemaGenerator {
             }
 
             if (typeof exclusiveMaximum === "number") {
-              if (this.target === "draft-4") {
+              if (this.target === "draft-4" || this.target === "openapi-3.0") {
                 json.maximum = exclusiveMaximum;
                 json.exclusiveMaximum = true;
               } else {
@@ -236,7 +236,11 @@ export class JSONSchemaGenerator {
             break;
           }
           case "null": {
-            _json.type = "null";
+            if (this.target === "openapi-3.0") {
+              _json.type = "string";
+              _json.nullable = true;
+              _json.enum = [null];
+            } else _json.type = "null";
             break;
           }
           case "any": {
@@ -332,18 +336,7 @@ export class JSONSchemaGenerator {
                 path: [...params.path, "anyOf", i],
               })
             );
-            if (this.target === "openapi-3.0") {
-              const nonNull = options.filter((x) => (x as any).type !== "null");
-              const hasNull = nonNull.length !== options.length;
-              if (nonNull.length === 1) {
-                Object.assign(json, nonNull[0]!);
-              } else {
-                json.anyOf = nonNull;
-              }
-              if (hasNull) (json as any).nullable = true;
-            } else {
-              json.anyOf = options;
-            }
+            json.anyOf = options;
             break;
           }
           case "intersection": {
@@ -368,13 +361,21 @@ export class JSONSchemaGenerator {
           case "tuple": {
             const json: JSONSchema.ArraySchema = _json as any;
             json.type = "array";
+
+            const prefixPath = this.target === "draft-2020-12" ? "prefixItems" : "items";
+            const restPath =
+              this.target === "draft-2020-12" ? "items" : this.target === "openapi-3.0" ? "items" : "additionalItems";
+
             const prefixItems = def.items.map((x, i) =>
-              this.process(x, { ...params, path: [...params.path, "prefixItems", i] })
+              this.process(x, {
+                ...params,
+                path: [...params.path, prefixPath, i],
+              })
             );
             const rest = def.rest
               ? this.process(def.rest, {
                   ...params,
-                  path: [...params.path, "items"],
+                  path: [...params.path, restPath, ...(this.target === "openapi-3.0" ? [def.items.length] : [])],
                 })
               : null;
 
@@ -384,9 +385,12 @@ export class JSONSchemaGenerator {
                 json.items = rest;
               }
             } else if (this.target === "openapi-3.0") {
-              json.items = [...prefixItems];
+              json.items = {
+                anyOf: prefixItems,
+              };
+
               if (rest) {
-                json.items.push(rest);
+                json.items.anyOf!.push(rest);
               }
               json.minItems = prefixItems.length;
               if (!rest) {
@@ -411,7 +415,7 @@ export class JSONSchemaGenerator {
           case "record": {
             const json: JSONSchema.ObjectSchema = _json as any;
             json.type = "object";
-            if (this.target !== "draft-4") {
+            if (this.target === "draft-7" || this.target === "draft-2020-12") {
               json.propertyNames = this.process(def.keyType, {
                 ...params,
                 path: [...params.path, "propertyNames"],
@@ -524,9 +528,8 @@ export class JSONSchemaGenerator {
           case "nullable": {
             const inner = this.process(def.innerType, params);
             if (this.target === "openapi-3.0") {
-              Object.assign(_json, inner);
-              (_json as any).nullable = true;
               result.ref = def.innerType;
+              _json.nullable = true;
             } else {
               _json.anyOf = [inner, { type: "null" }];
             }

package/src/v4/core/versions.ts

@@ -1,5 +1,5 @@
 export const version = {
   major: 4,
   minor: 1,
-  patch: 2 as number,
+  patch: 4 as number,
 } as const;

package/v4/core/to-json-schema.cjs

@@ -101,7 +101,7 @@ class JSONSchemaGenerator {
                         else
                             json.type = "number";
                         if (typeof exclusiveMinimum === "number") {
-                            if (this.target === "draft-4") {
+                            if (this.target === "draft-4" || this.target === "openapi-3.0") {
                                 json.minimum = exclusiveMinimum;
                                 json.exclusiveMinimum = true;
                             }
@@ -119,7 +119,7 @@ class JSONSchemaGenerator {
                             }
                         }
                         if (typeof exclusiveMaximum === "number") {
-                            if (this.target === "draft-4") {
+                            if (this.target === "draft-4" || this.target === "openapi-3.0") {
                                 json.maximum = exclusiveMaximum;
                                 json.exclusiveMaximum = true;
                             }
@@ -158,7 +158,13 @@ class JSONSchemaGenerator {
                         break;
                     }
                     case "null": {
-                        _json.type = "null";
+                        if (this.target === "openapi-3.0") {
+                            _json.type = "string";
+                            _json.nullable = true;
+                            _json.enum = [null];
+                        }
+                        else
+                            _json.type = "null";
                         break;
                     }
                     case "any": {
@@ -250,21 +256,7 @@ class JSONSchemaGenerator {
                             ...params,
                             path: [...params.path, "anyOf", i],
                         }));
-                        if (this.target === "openapi-3.0") {
-                            const nonNull = options.filter((x) => x.type !== "null");
-                            const hasNull = nonNull.length !== options.length;
-                            if (nonNull.length === 1) {
-                                Object.assign(json, nonNull[0]);
-                            }
-                            else {
-                                json.anyOf = nonNull;
-                            }
-                            if (hasNull)
-                                json.nullable = true;
-                        }
-                        else {
-                            json.anyOf = options;
-                        }
+                        json.anyOf = options;
                         break;
                     }
                     case "intersection": {
@@ -288,11 +280,16 @@ class JSONSchemaGenerator {
                     case "tuple": {
                         const json = _json;
                         json.type = "array";
-                        const prefixItems = def.items.map((x, i) => this.process(x, { ...params, path: [...params.path, "prefixItems", i] }));
+                        const prefixPath = this.target === "draft-2020-12" ? "prefixItems" : "items";
+                        const restPath = this.target === "draft-2020-12" ? "items" : this.target === "openapi-3.0" ? "items" : "additionalItems";
+                        const prefixItems = def.items.map((x, i) => this.process(x, {
+                            ...params,
+                            path: [...params.path, prefixPath, i],
+                        }));
                         const rest = def.rest
                             ? this.process(def.rest, {
                                 ...params,
-                                path: [...params.path, "items"],
+                                path: [...params.path, restPath, ...(this.target === "openapi-3.0" ? [def.items.length] : [])],
                             })
                             : null;
                         if (this.target === "draft-2020-12") {
@@ -302,9 +299,11 @@ class JSONSchemaGenerator {
                             }
                         }
                         else if (this.target === "openapi-3.0") {
-                            json.items = [...prefixItems];
+                            json.items = {
+                                anyOf: prefixItems,
+                            };
                             if (rest) {
-                                json.items.push(rest);
+                                json.items.anyOf.push(rest);
                             }
                             json.minItems = prefixItems.length;
                             if (!rest) {
@@ -328,7 +327,7 @@ class JSONSchemaGenerator {
                     case "record": {
                         const json = _json;
                         json.type = "object";
-                        if (this.target !== "draft-4") {
+                        if (this.target === "draft-7" || this.target === "draft-2020-12") {
                             json.propertyNames = this.process(def.keyType, {
                                 ...params,
                                 path: [...params.path, "propertyNames"],
@@ -454,9 +453,8 @@ class JSONSchemaGenerator {
                     case "nullable": {
                         const inner = this.process(def.innerType, params);
                         if (this.target === "openapi-3.0") {
-                            Object.assign(_json, inner);
-                            _json.nullable = true;
                             result.ref = def.innerType;
+                            _json.nullable = true;
                         }
                         else {
                             _json.anyOf = [inner, { type: "null" }];

package/v4/core/to-json-schema.js

@@ -97,7 +97,7 @@ export class JSONSchemaGenerator {
                         else
                             json.type = "number";
                         if (typeof exclusiveMinimum === "number") {
-                            if (this.target === "draft-4") {
+                            if (this.target === "draft-4" || this.target === "openapi-3.0") {
                                 json.minimum = exclusiveMinimum;
                                 json.exclusiveMinimum = true;
                             }
@@ -115,7 +115,7 @@ export class JSONSchemaGenerator {
                             }
                         }
                         if (typeof exclusiveMaximum === "number") {
-                            if (this.target === "draft-4") {
+                            if (this.target === "draft-4" || this.target === "openapi-3.0") {
                                 json.maximum = exclusiveMaximum;
                                 json.exclusiveMaximum = true;
                             }
@@ -154,7 +154,13 @@ export class JSONSchemaGenerator {
                         break;
                     }
                     case "null": {
-                        _json.type = "null";
+                        if (this.target === "openapi-3.0") {
+                            _json.type = "string";
+                            _json.nullable = true;
+                            _json.enum = [null];
+                        }
+                        else
+                            _json.type = "null";
                         break;
                     }
                     case "any": {
@@ -246,21 +252,7 @@ export class JSONSchemaGenerator {
                             ...params,
                             path: [...params.path, "anyOf", i],
                         }));
-                        if (this.target === "openapi-3.0") {
-                            const nonNull = options.filter((x) => x.type !== "null");
-                            const hasNull = nonNull.length !== options.length;
-                            if (nonNull.length === 1) {
-                                Object.assign(json, nonNull[0]);
-                            }
-                            else {
-                                json.anyOf = nonNull;
-                            }
-                            if (hasNull)
-                                json.nullable = true;
-                        }
-                        else {
-                            json.anyOf = options;
-                        }
+                        json.anyOf = options;
                         break;
                     }
                     case "intersection": {
@@ -284,11 +276,16 @@ export class JSONSchemaGenerator {
                     case "tuple": {
                         const json = _json;
                         json.type = "array";
-                        const prefixItems = def.items.map((x, i) => this.process(x, { ...params, path: [...params.path, "prefixItems", i] }));
+                        const prefixPath = this.target === "draft-2020-12" ? "prefixItems" : "items";
+                        const restPath = this.target === "draft-2020-12" ? "items" : this.target === "openapi-3.0" ? "items" : "additionalItems";
+                        const prefixItems = def.items.map((x, i) => this.process(x, {
+                            ...params,
+                            path: [...params.path, prefixPath, i],
+                        }));
                         const rest = def.rest
                             ? this.process(def.rest, {
                                 ...params,
-                                path: [...params.path, "items"],
+                                path: [...params.path, restPath, ...(this.target === "openapi-3.0" ? [def.items.length] : [])],
                             })
                             : null;
                         if (this.target === "draft-2020-12") {
@@ -298,9 +295,11 @@ export class JSONSchemaGenerator {
                             }
                         }
                         else if (this.target === "openapi-3.0") {
-                            json.items = [...prefixItems];
+                            json.items = {
+                                anyOf: prefixItems,
+                            };
                             if (rest) {
-                                json.items.push(rest);
+                                json.items.anyOf.push(rest);
                             }
                             json.minItems = prefixItems.length;
                             if (!rest) {
@@ -324,7 +323,7 @@ export class JSONSchemaGenerator {
                     case "record": {
                         const json = _json;
                         json.type = "object";
-                        if (this.target !== "draft-4") {
+                        if (this.target === "draft-7" || this.target === "draft-2020-12") {
                             json.propertyNames = this.process(def.keyType, {
                                 ...params,
                                 path: [...params.path, "propertyNames"],
@@ -450,9 +449,8 @@ export class JSONSchemaGenerator {
                     case "nullable": {
                         const inner = this.process(def.innerType, params);
                         if (this.target === "openapi-3.0") {
-                            Object.assign(_json, inner);
-                            _json.nullable = true;
                             result.ref = def.innerType;
+                            _json.nullable = true;
                         }
                         else {
                             _json.anyOf = [inner, { type: "null" }];

package/v4/core/versions.cjs

@@ -4,5 +4,5 @@ exports.version = void 0;
 exports.version = {
     major: 4,
     minor: 1,
-    patch: 2,
+    patch: 4,
 };

package/v4/core/versions.js

@@ -1,5 +1,5 @@
 export const version = {
     major: 4,
     minor: 1,
-    patch: 2,
+    patch: 4,
 };