zod 4.5.2 → 4.5.3

package/package.json

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

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

@@ -1149,7 +1149,7 @@ describe("toJSONSchema", () => {
     ]);
   });
 
-  test("record filters enum values to strings and numbers for required", () => {
+  test("record stringifies numeric enum keys for propertyNames and required", () => {
     enum NumberEnum {
       Zero = 0,
       One = 1,
@@ -1164,20 +1164,124 @@ describe("toJSONSchema", () => {
         },
         "propertyNames": {
           "enum": [
-            0,
-            1,
+            "0",
+            "1",
           ],
-          "type": "number",
+          "type": "string",
         },
         "required": [
-          0,
-          1,
+          "0",
+          "1",
         ],
         "type": "object",
       }
     `);
   });
 
+  test("record with a numeric key emits propertyNames over the numeric-string form", () => {
+    expect(z.toJSONSchema(z.record(z.number(), z.boolean())).propertyNames).toEqual({
+      type: "string",
+      pattern: "^-?\\d+(?:\\.\\d+)?$",
+    });
+    // range checks can't apply to a key, so only the integer shape survives
+    expect(z.toJSONSchema(z.record(z.int32(), z.boolean())).propertyNames).toEqual({
+      type: "string",
+      pattern: "^-?\\d+$",
+    });
+    expect(z.toJSONSchema(z.record(z.literal([1, 2]), z.boolean()))).toMatchObject({
+      propertyNames: { type: "string", enum: ["1", "2"] },
+      required: ["1", "2"],
+    });
+    expect(z.toJSONSchema(z.record(z.literal(1), z.boolean())).propertyNames).toEqual({
+      type: "string",
+      const: "1",
+    });
+  });
+
+  test("record key rewrite reaches through wrappers and union branches", () => {
+    const numericString = { type: "string", pattern: "^-?\\d+(?:\\.\\d+)?$" };
+    // a wrapper only carries its inner type once the refs are flattened, so this is decided after the record itself is emitted
+    expect(
+      z.toJSONSchema(
+        z.record(
+          z.lazy(() => z.number()),
+          z.boolean()
+        )
+      ).propertyNames
+    ).toEqual(numericString);
+    expect(z.toJSONSchema(z.record(z.number().pipe(z.number()), z.boolean())).propertyNames).toEqual(numericString);
+    expect(z.toJSONSchema(z.record(z.number().readonly(), z.boolean())).propertyNames).toMatchObject(numericString);
+    expect(z.toJSONSchema(z.record(z.union([z.literal("Tuna"), z.literal(21)]), z.string()))).toMatchObject({
+      propertyNames: {
+        anyOf: [
+          { type: "string", const: "Tuna" },
+          { type: "string", const: "21" },
+        ],
+      },
+      required: ["Tuna", "21"],
+    });
+  });
+
+  test("record with a numeric key inlines an extracted key, and leaves a string one referenced", () => {
+    expect(z.toJSONSchema(z.record(z.number().meta({ id: "Num" }), z.boolean())).propertyNames).toEqual({
+      type: "string",
+      pattern: "^-?\\d+(?:\\.\\d+)?$",
+    });
+    expect(z.toJSONSchema(z.record(z.string().meta({ id: "Str" }), z.boolean())).propertyNames).toEqual({
+      $ref: "#/$defs/Str",
+    });
+    // the value position still wants the number form, so the two cannot share one def
+    const key = z.number().meta({ id: "Shared" });
+    expect(z.toJSONSchema(z.object({ a: key, b: z.record(key, z.string()) }))).toMatchObject({
+      properties: { a: { $ref: "#/$defs/Shared" }, b: { propertyNames: { type: "string" } } },
+      $defs: { Shared: { type: "number" } },
+    });
+  });
+
+  test("record key rewrite reaches a wrapped record", () => {
+    // the flatten copies a record's properties onto its wrapper by reference, so the rewrite has to find every copy
+    expect(z.toJSONSchema(z.record(z.number(), z.boolean()).optional()).propertyNames).toEqual({
+      type: "string",
+      pattern: "^-?\\d+(?:\\.\\d+)?$",
+    });
+    expect(z.toJSONSchema(z.object({ a: z.record(z.literal([1, 2]), z.boolean()).optional() }))).toMatchObject({
+      properties: { a: { propertyNames: { type: "string", enum: ["1", "2"] }, required: ["1", "2"] } },
+    });
+  });
+
+  test("record with a recursive key converts without looping", () => {
+    const numeric: any = z.lazy(() => z.union([z.number(), numeric]));
+    expect(z.toJSONSchema(z.record(numeric, z.boolean())).propertyNames).toMatchObject({
+      anyOf: [{ type: "string", pattern: "^-?\\d+(?:\\.\\d+)?$" }, { $ref: "#/$defs/__schema0" }],
+    });
+    // a key with nothing to re-express keeps the reference it had
+    const stringy: any = z.lazy(() => z.union([z.string(), stringy]));
+    expect(z.toJSONSchema(z.record(stringy, z.boolean())).propertyNames).toEqual({ $ref: "#/$defs/__schema0" });
+    expect(
+      z.toJSONSchema(z.record(z.union([z.literal("a"), z.literal("b")]).meta({ id: "Keys" }), z.boolean()))
+        .propertyNames
+    ).toEqual({ $ref: "#/$defs/Keys" });
+  });
+
+  test("record with a heterogeneous key stringifies only its numeric members", () => {
+    // a mixed key carries no `type`, so the numeric members are caught by value rather than by type
+    expect(z.toJSONSchema(z.record(z.literal(["a", 1]), z.boolean()))).toMatchObject({
+      propertyNames: { enum: ["a", "1"] },
+      required: ["a", "1"],
+    });
+    // a member no key can spell is left as it was, since the parser only ever retries a key as a number
+    expect(z.toJSONSchema(z.record(z.literal(["a", true]) as any, z.boolean())).propertyNames).toEqual({
+      enum: ["a", true],
+    });
+  });
+
+  test("record stringifies required for every target", () => {
+    const schema = z.record(z.literal([1, 2]), z.boolean());
+    for (const target of ["draft-2020-12", "draft-7", "draft-4", "openapi-3.0"] as const) {
+      expect(z.toJSONSchema(schema, { target }).required).toEqual(["1", "2"]);
+    }
+  });
+
   test("strict record with regex key uses propertyNames", () => {
     const schema = z.record(z.string().regex(/^label:[a-z]{2}$/), z.string());
 
@@ -3022,6 +3126,34 @@ test("large registry converts in linear time", () => {
   expect(folded.elapsed).toBeLessThan(plain.elapsed * 4 + 100);
 });
 
+test("a registry of records with numeric keys converts in linear time", () => {
+  const count = 2000;
+  const convert = (key: (i: number) => z.core.$ZodType) => {
+    const registry = z.registry<{ id: string }>();
+    for (let i = 0; i < count; i++) {
+      registry.add(z.object({ m: z.record(key(i) as z.core.$ZodRecordKey, z.boolean()) }), { id: `Type${i}` });
+    }
+    const start = performance.now();
+    const { schemas } = z.toJSONSchema(registry, { uri: (id) => `https://example.com/${id}.json` });
+    return { schemas, elapsed: performance.now() - start };
+  };
+
+  const string = convert(() => z.string());
+  const numeric = convert(() => z.number());
+  expect(numeric.schemas.Type0).toMatchObject({
+    properties: { m: { propertyNames: { type: "string", pattern: "^-?\\d+(?:\\.\\d+)?$" } } },
+  });
+
+  // The rewrite has to find every carrier the flatten copied `propertyNames` onto, which means a pass over the whole seen map. Running that once per record rather than once per conversion cost ~10x at this size. A string key needs no rewrite at all, so comparing against it keeps this independent of how fast the machine is.
+  expect(numeric.elapsed).toBeLessThan(string.elapsed * 2 + 50);
+
+  // An extracted key resolves through a map built once per conversion rather than a search per reference. There is no stable timing control for that — extraction has its own $defs cost, which swamps the difference — so this only pins the shape.
+  const extracted = convert((i) => z.number().meta({ id: `Key${i}` }));
+  expect(extracted.schemas.Type0).toMatchObject({
+    properties: { m: { propertyNames: { type: "string", pattern: "^-?\\d+(?:\\.\\d+)?$" } } },
+  });
+});
+
 test("registry extracts unregistered subschemas into __shared", () => {
   const registry = z.registry<{ id: string }>();
   const address = z.object({ street: z.string() }).meta({ id: "Address" });

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

@@ -1,11 +1,13 @@
 import type * as checks from "./checks.js";
 import type * as JSONSchema from "./json-schema.js";
+import * as regexes from "./regexes.js";
 import type { $ZodRegistry } from "./registries.js";
 import type * as schemas from "./schemas.js";
 import {
   type ProcessParams,
   type Processor,
   type RegistryToJSONSchemaParams,
+  type Seen,
   type ToJSONSchemaContext,
   type ToJSONSchemaParams,
   type ZodStandardJSONSchemaPayload,
@@ -46,11 +48,11 @@ export const stringProcessor: Processor<schemas.$ZodString> = (schema, ctx, _jso
   }
   if (contentEncoding) json.contentEncoding = contentEncoding;
   if (patterns && patterns.size > 0) {
-    const regexes = [...patterns];
-    if (regexes.length === 1) json.pattern = regexes[0]!.source;
-    else if (regexes.length > 1) {
+    const patternList = [...patterns];
+    if (patternList.length === 1) json.pattern = patternList[0]!.source;
+    else if (patternList.length > 1) {
       json.allOf = [
-        ...regexes.map((regex) => ({
+        ...patternList.map((regex) => ({
           ...(ctx.target === "draft-07" || ctx.target === "draft-04" || ctx.target === "openapi-3.0"
             ? ({ type: "string" } as const)
             : {}),
@@ -475,6 +477,85 @@ export const tupleProcessor: Processor<schemas.$ZodTuple> = (schema, ctx, _json,
   if (typeof maximum === "number") json.maxItems = maximum;
 };
 
+/** JSON object keys are always strings, so a numeric record key schema is re-expressed over the
+ * numeric-string form the record parser matches. Deferred to `finalize`, after the flatten: a key
+ * behind a wrapper only carries its own `type` before then, and a union key only has its branches.
+ *
+ * A numeric bound cannot apply to a property name, so `minimum` and its siblings are dropped rather
+ * than carried over: keeping them beside `type: "string"` reproduces the match-nothing schema this
+ * exists to fix. A key that carries one therefore emits wider than the record parses — `z.record(z.number().min(5), V)`
+ * accepts `"3"` — which is the deliberate trade, since throwing on it would reject an ordinary schema
+ * outright. */
+function stringifyKeyNames(
+  bySchema: Map<JSONSchema.BaseSchema, Seen>,
+  json: JSONSchema.BaseSchema,
+  visited: Set<JSONSchema.BaseSchema>
+): JSONSchema.BaseSchema {
+  // an extracted key that rewrites cannot go on sharing its definition — the string form a key position needs is not the number form every other reference wants — so it inlines. One that does not rewrite keeps the `$ref`.
+  if (json.$ref) {
+    // a recursive key holds its own reference inside its definition, so a node already on the path is left alone rather than resolved again
+    if (visited.has(json)) return json;
+    visited.add(json);
+    const def = bySchema.get(json)?.def;
+    if (!def) return json;
+    const inlined = stringifyKeyNames(bySchema, def, visited);
+    return inlined === def ? json : inlined;
+  }
+
+  for (const keyword of ["anyOf", "oneOf"] as const) {
+    const branches = json[keyword];
+    if (!Array.isArray(branches)) continue;
+    const mapped = branches.map((branch) => stringifyKeyNames(bySchema, branch, visited));
+    // rebuilding regardless would detach a key that had nothing to re-express, dropping its `$ref` and leaking the internal `id`
+    if (mapped.some((branch, i) => branch !== branches[i])) json = { ...json, [keyword]: mapped };
+  }
+
+  // a member that already admits a string leaves the key unconstrained, so the node's own type re-expresses only when every member is numeric
+  const types = Array.isArray(json.type) ? json.type : [json.type];
+  const numericType = !types.includes("string") && types.some((t) => t === "number" || t === "integer");
+  // a heterogeneous key carries no type at all, so its numeric members are caught here instead
+  const values = json.enum ?? (json.const !== undefined ? [json.const] : undefined);
+  if (!numericType && !values?.some((v) => typeof v === "number")) return json;
+
+  const { minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, format, id, ...rest } = json;
+  if (rest.enum) rest.enum = rest.enum.map((v) => (typeof v === "number" ? String(v) : v));
+  else if (typeof rest.const === "number") rest.const = String(rest.const);
+  // a heterogeneous key keeps its absent type: the stringified members already say what a key may be
+  if (!numericType) return rest;
+  rest.type = "string";
+  if (!values) rest.pattern = (types.includes("number") ? regexes.number : regexes.integer).source;
+  return rest;
+}
+
+/** Every record of one conversion, so the carriers are found in a single pass rather than once per record. */
+const pendingRecords = new WeakMap<ToJSONSchemaContext, schemas.$ZodType[]>();
+
+function rewriteKeyNames(ctx: ToJSONSchemaContext): void {
+  // an extracted key is resolved by the object `extractToDef` left in its place, so the map is built once rather than searched per reference. `_zod.toJSONSchema` can hand the same object to two schemas, so the first entry carrying a body wins, as a search would have found it.
+  const bySchema = new Map<JSONSchema.BaseSchema, Seen>();
+  for (const entry of ctx.seen.values()) {
+    if (entry.def && !bySchema.has(entry.schema)) bySchema.set(entry.schema, entry);
+  }
+
+  const rewrites = new Map<JSONSchema.BaseSchema, JSONSchema.BaseSchema>();
+  for (const record of pendingRecords.get(ctx) ?? []) {
+    const seen = ctx.seen.get(record);
+    const names = (seen?.def ?? seen?.schema)?.propertyNames;
+    if (!names || names === true || rewrites.has(names)) continue;
+    const rewritten = stringifyKeyNames(bySchema, names, new Set());
+    if (rewritten !== names) rewrites.set(names, rewritten);
+  }
+  if (!rewrites.size) return;
+
+  // the flatten has already copied each record's own properties onto every wrapper by reference, and an extracted body is another such copy, so every carrier holding a rewritten key is updated together
+  for (const entry of ctx.seen.values()) {
+    for (const carrier of [entry.schema, entry.def]) {
+      const rewritten = carrier && rewrites.get(carrier.propertyNames as JSONSchema.BaseSchema);
+      if (rewritten) carrier!.propertyNames = rewritten;
+    }
+  }
+}
+
 export const recordProcessor: Processor<schemas.$ZodRecord> = (schema, ctx, _json, params) => {
   const json = _json as JSONSchema.ObjectSchema;
   const def = schema._zod.def as schemas.$ZodRecordDef;
@@ -502,6 +583,13 @@ export const recordProcessor: Processor<schemas.$ZodRecord> = (schema, ctx, _jso
         ...params,
         path: [...params.path, "propertyNames"],
       });
+      let pending = pendingRecords.get(ctx);
+      if (!pending) {
+        pending = [];
+        pendingRecords.set(ctx, pending);
+        ctx.deferred.push(() => rewriteKeyNames(ctx));
+      }
+      pending.push(schema);
     }
     json.additionalProperties = process(def.valueType, ctx as any, {
       ...params,
@@ -519,7 +607,7 @@ export const recordProcessor: Processor<schemas.$ZodRecord> = (schema, ctx, _jso
     );
 
     if (validKeyValues.length > 0) {
-      json.required = validKeyValues as string[];
+      json.required = validKeyValues.map(String);
     }
   }
 };

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

@@ -142,6 +142,8 @@ export interface ToJSONSchemaContext {
   reused: "ref" | "inline";
   /** The `allOf` array of each intersection encountered during traversal, innermost first. `finalize` folds every emitted object holding one; see `foldIntersection`. */
   intersections: JSONSchema.BaseSchema[][];
+  /** Rewrites a processor deferred to `finalize`, where the flatten has resolved every ref and the union branches are in place. */
+  deferred: (() => void)[];
   external?:
     | {
         registry: $ZodRegistry<{ id?: string | undefined }>;
@@ -180,6 +182,7 @@ export function initializeContext(params: JSONSchemaGeneratorParams): ToJSONSche
     cycles: params?.cycles ?? "ref",
     reused: params?.reused ?? "inline",
     intersections: [],
+    deferred: [],
     external: params?.external ?? undefined,
   };
 }
@@ -660,6 +663,8 @@ export function finalize<T extends schemas.$ZodType>(
       }
     }
 
+    for (const rewrite of ctx.deferred) rewrite();
+
     // After flattening, every member that was extracted is a `$ref`, so the fold sees the final shape. A schema that inherits an intersection — through `z.lazy`, or any `ref` chain — holds the same `allOf` array, so fold by array identity to catch every copy.
     if (ctx.intersections.length) {
       const carriers = new Map<JSONSchema.BaseSchema[], JSONSchema.BaseSchema[]>();

package/src/v4/core/versions.ts

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

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

@@ -1,7 +1,31 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.allProcessors = exports.lazyProcessor = exports.optionalProcessor = exports.promiseProcessor = exports.readonlyProcessor = exports.pipeProcessor = exports.catchProcessor = exports.prefaultProcessor = exports.defaultProcessor = exports.nonoptionalProcessor = exports.nullableProcessor = exports.recordProcessor = exports.tupleProcessor = exports.intersectionProcessor = exports.unionProcessor = exports.objectProcessor = exports.arrayProcessor = exports.setProcessor = exports.mapProcessor = exports.transformProcessor = exports.functionProcessor = exports.customProcessor = exports.successProcessor = exports.fileProcessor = exports.templateLiteralProcessor = exports.nanProcessor = exports.literalProcessor = exports.enumProcessor = exports.dateProcessor = exports.unknownProcessor = exports.anyProcessor = exports.neverProcessor = exports.voidProcessor = exports.undefinedProcessor = exports.nullProcessor = exports.symbolProcessor = exports.bigintProcessor = exports.booleanProcessor = exports.numberProcessor = exports.stringProcessor = void 0;
 exports.toJSONSchema = toJSONSchema;
+const regexes = __importStar(require("./regexes.cjs"));
 const to_json_schema_js_1 = require("./to-json-schema.cjs");
 const util_js_1 = require("./util.cjs");
 const formatMap = {
@@ -34,12 +58,12 @@ const stringProcessor = (schema, ctx, _json, _params) => {
     if (contentEncoding)
         json.contentEncoding = contentEncoding;
     if (patterns && patterns.size > 0) {
-        const regexes = [...patterns];
-        if (regexes.length === 1)
-            json.pattern = regexes[0].source;
-        else if (regexes.length > 1) {
+        const patternList = [...patterns];
+        if (patternList.length === 1)
+            json.pattern = patternList[0].source;
+        else if (patternList.length > 1) {
             json.allOf = [
-                ...regexes.map((regex) => ({
+                ...patternList.map((regex) => ({
                     ...(ctx.target === "draft-07" || ctx.target === "draft-04" || ctx.target === "openapi-3.0"
                         ? { type: "string" }
                         : {}),
@@ -461,6 +485,87 @@ const tupleProcessor = (schema, ctx, _json, params) => {
         json.maxItems = maximum;
 };
 exports.tupleProcessor = tupleProcessor;
+/** JSON object keys are always strings, so a numeric record key schema is re-expressed over the
+ * numeric-string form the record parser matches. Deferred to `finalize`, after the flatten: a key
+ * behind a wrapper only carries its own `type` before then, and a union key only has its branches.
+ *
+ * A numeric bound cannot apply to a property name, so `minimum` and its siblings are dropped rather
+ * than carried over: keeping them beside `type: "string"` reproduces the match-nothing schema this
+ * exists to fix. A key that carries one therefore emits wider than the record parses — `z.record(z.number().min(5), V)`
+ * accepts `"3"` — which is the deliberate trade, since throwing on it would reject an ordinary schema
+ * outright. */
+function stringifyKeyNames(bySchema, json, visited) {
+    // an extracted key that rewrites cannot go on sharing its definition — the string form a key position needs is not the number form every other reference wants — so it inlines. One that does not rewrite keeps the `$ref`.
+    if (json.$ref) {
+        // a recursive key holds its own reference inside its definition, so a node already on the path is left alone rather than resolved again
+        if (visited.has(json))
+            return json;
+        visited.add(json);
+        const def = bySchema.get(json)?.def;
+        if (!def)
+            return json;
+        const inlined = stringifyKeyNames(bySchema, def, visited);
+        return inlined === def ? json : inlined;
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const branches = json[keyword];
+        if (!Array.isArray(branches))
+            continue;
+        const mapped = branches.map((branch) => stringifyKeyNames(bySchema, branch, visited));
+        // rebuilding regardless would detach a key that had nothing to re-express, dropping its `$ref` and leaking the internal `id`
+        if (mapped.some((branch, i) => branch !== branches[i]))
+            json = { ...json, [keyword]: mapped };
+    }
+    // a member that already admits a string leaves the key unconstrained, so the node's own type re-expresses only when every member is numeric
+    const types = Array.isArray(json.type) ? json.type : [json.type];
+    const numericType = !types.includes("string") && types.some((t) => t === "number" || t === "integer");
+    // a heterogeneous key carries no type at all, so its numeric members are caught here instead
+    const values = json.enum ?? (json.const !== undefined ? [json.const] : undefined);
+    if (!numericType && !values?.some((v) => typeof v === "number"))
+        return json;
+    const { minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, format, id, ...rest } = json;
+    if (rest.enum)
+        rest.enum = rest.enum.map((v) => (typeof v === "number" ? String(v) : v));
+    else if (typeof rest.const === "number")
+        rest.const = String(rest.const);
+    // a heterogeneous key keeps its absent type: the stringified members already say what a key may be
+    if (!numericType)
+        return rest;
+    rest.type = "string";
+    if (!values)
+        rest.pattern = (types.includes("number") ? regexes.number : regexes.integer).source;
+    return rest;
+}
+/** Every record of one conversion, so the carriers are found in a single pass rather than once per record. */
+const pendingRecords = new WeakMap();
+function rewriteKeyNames(ctx) {
+    // an extracted key is resolved by the object `extractToDef` left in its place, so the map is built once rather than searched per reference. `_zod.toJSONSchema` can hand the same object to two schemas, so the first entry carrying a body wins, as a search would have found it.
+    const bySchema = new Map();
+    for (const entry of ctx.seen.values()) {
+        if (entry.def && !bySchema.has(entry.schema))
+            bySchema.set(entry.schema, entry);
+    }
+    const rewrites = new Map();
+    for (const record of pendingRecords.get(ctx) ?? []) {
+        const seen = ctx.seen.get(record);
+        const names = (seen?.def ?? seen?.schema)?.propertyNames;
+        if (!names || names === true || rewrites.has(names))
+            continue;
+        const rewritten = stringifyKeyNames(bySchema, names, new Set());
+        if (rewritten !== names)
+            rewrites.set(names, rewritten);
+    }
+    if (!rewrites.size)
+        return;
+    // the flatten has already copied each record's own properties onto every wrapper by reference, and an extracted body is another such copy, so every carrier holding a rewritten key is updated together
+    for (const entry of ctx.seen.values()) {
+        for (const carrier of [entry.schema, entry.def]) {
+            const rewritten = carrier && rewrites.get(carrier.propertyNames);
+            if (rewritten)
+                carrier.propertyNames = rewritten;
+        }
+    }
+}
 const recordProcessor = (schema, ctx, _json, params) => {
     const json = _json;
     const def = schema._zod.def;
@@ -487,6 +592,13 @@ const recordProcessor = (schema, ctx, _json, params) => {
                 ...params,
                 path: [...params.path, "propertyNames"],
             });
+            let pending = pendingRecords.get(ctx);
+            if (!pending) {
+                pending = [];
+                pendingRecords.set(ctx, pending);
+                ctx.deferred.push(() => rewriteKeyNames(ctx));
+            }
+            pending.push(schema);
         }
         json.additionalProperties = (0, to_json_schema_js_1.process)(def.valueType, ctx, {
             ...params,
@@ -500,7 +612,7 @@ const recordProcessor = (schema, ctx, _json, params) => {
     if (keyValues && !def.partial && !omittableOnInput) {
         const validKeyValues = [...keyValues].filter((v) => typeof v === "string" || typeof v === "number");
         if (validKeyValues.length > 0) {
-            json.required = validKeyValues;
+            json.required = validKeyValues.map(String);
         }
     }
 };

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

@@ -1,3 +1,4 @@
+import * as regexes from "./regexes.js";
 import { extractDefs, finalize, handleUnrepresentable, initializeContext, process, } from "./to-json-schema.js";
 import { assignProp, getEnumValues } from "./util.js";
 const formatMap = {
@@ -30,12 +31,12 @@ export const stringProcessor = (schema, ctx, _json, _params) => {
     if (contentEncoding)
         json.contentEncoding = contentEncoding;
     if (patterns && patterns.size > 0) {
-        const regexes = [...patterns];
-        if (regexes.length === 1)
-            json.pattern = regexes[0].source;
-        else if (regexes.length > 1) {
+        const patternList = [...patterns];
+        if (patternList.length === 1)
+            json.pattern = patternList[0].source;
+        else if (patternList.length > 1) {
             json.allOf = [
-                ...regexes.map((regex) => ({
+                ...patternList.map((regex) => ({
                     ...(ctx.target === "draft-07" || ctx.target === "draft-04" || ctx.target === "openapi-3.0"
                         ? { type: "string" }
                         : {}),
@@ -429,6 +430,87 @@ export const tupleProcessor = (schema, ctx, _json, params) => {
     if (typeof maximum === "number")
         json.maxItems = maximum;
 };
+/** JSON object keys are always strings, so a numeric record key schema is re-expressed over the
+ * numeric-string form the record parser matches. Deferred to `finalize`, after the flatten: a key
+ * behind a wrapper only carries its own `type` before then, and a union key only has its branches.
+ *
+ * A numeric bound cannot apply to a property name, so `minimum` and its siblings are dropped rather
+ * than carried over: keeping them beside `type: "string"` reproduces the match-nothing schema this
+ * exists to fix. A key that carries one therefore emits wider than the record parses — `z.record(z.number().min(5), V)`
+ * accepts `"3"` — which is the deliberate trade, since throwing on it would reject an ordinary schema
+ * outright. */
+function stringifyKeyNames(bySchema, json, visited) {
+    // an extracted key that rewrites cannot go on sharing its definition — the string form a key position needs is not the number form every other reference wants — so it inlines. One that does not rewrite keeps the `$ref`.
+    if (json.$ref) {
+        // a recursive key holds its own reference inside its definition, so a node already on the path is left alone rather than resolved again
+        if (visited.has(json))
+            return json;
+        visited.add(json);
+        const def = bySchema.get(json)?.def;
+        if (!def)
+            return json;
+        const inlined = stringifyKeyNames(bySchema, def, visited);
+        return inlined === def ? json : inlined;
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const branches = json[keyword];
+        if (!Array.isArray(branches))
+            continue;
+        const mapped = branches.map((branch) => stringifyKeyNames(bySchema, branch, visited));
+        // rebuilding regardless would detach a key that had nothing to re-express, dropping its `$ref` and leaking the internal `id`
+        if (mapped.some((branch, i) => branch !== branches[i]))
+            json = { ...json, [keyword]: mapped };
+    }
+    // a member that already admits a string leaves the key unconstrained, so the node's own type re-expresses only when every member is numeric
+    const types = Array.isArray(json.type) ? json.type : [json.type];
+    const numericType = !types.includes("string") && types.some((t) => t === "number" || t === "integer");
+    // a heterogeneous key carries no type at all, so its numeric members are caught here instead
+    const values = json.enum ?? (json.const !== undefined ? [json.const] : undefined);
+    if (!numericType && !values?.some((v) => typeof v === "number"))
+        return json;
+    const { minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, format, id, ...rest } = json;
+    if (rest.enum)
+        rest.enum = rest.enum.map((v) => (typeof v === "number" ? String(v) : v));
+    else if (typeof rest.const === "number")
+        rest.const = String(rest.const);
+    // a heterogeneous key keeps its absent type: the stringified members already say what a key may be
+    if (!numericType)
+        return rest;
+    rest.type = "string";
+    if (!values)
+        rest.pattern = (types.includes("number") ? regexes.number : regexes.integer).source;
+    return rest;
+}
+/** Every record of one conversion, so the carriers are found in a single pass rather than once per record. */
+const pendingRecords = new WeakMap();
+function rewriteKeyNames(ctx) {
+    // an extracted key is resolved by the object `extractToDef` left in its place, so the map is built once rather than searched per reference. `_zod.toJSONSchema` can hand the same object to two schemas, so the first entry carrying a body wins, as a search would have found it.
+    const bySchema = new Map();
+    for (const entry of ctx.seen.values()) {
+        if (entry.def && !bySchema.has(entry.schema))
+            bySchema.set(entry.schema, entry);
+    }
+    const rewrites = new Map();
+    for (const record of pendingRecords.get(ctx) ?? []) {
+        const seen = ctx.seen.get(record);
+        const names = (seen?.def ?? seen?.schema)?.propertyNames;
+        if (!names || names === true || rewrites.has(names))
+            continue;
+        const rewritten = stringifyKeyNames(bySchema, names, new Set());
+        if (rewritten !== names)
+            rewrites.set(names, rewritten);
+    }
+    if (!rewrites.size)
+        return;
+    // the flatten has already copied each record's own properties onto every wrapper by reference, and an extracted body is another such copy, so every carrier holding a rewritten key is updated together
+    for (const entry of ctx.seen.values()) {
+        for (const carrier of [entry.schema, entry.def]) {
+            const rewritten = carrier && rewrites.get(carrier.propertyNames);
+            if (rewritten)
+                carrier.propertyNames = rewritten;
+        }
+    }
+}
 export const recordProcessor = (schema, ctx, _json, params) => {
     const json = _json;
     const def = schema._zod.def;
@@ -455,6 +537,13 @@ export const recordProcessor = (schema, ctx, _json, params) => {
                 ...params,
                 path: [...params.path, "propertyNames"],
             });
+            let pending = pendingRecords.get(ctx);
+            if (!pending) {
+                pending = [];
+                pendingRecords.set(ctx, pending);
+                ctx.deferred.push(() => rewriteKeyNames(ctx));
+            }
+            pending.push(schema);
         }
         json.additionalProperties = process(def.valueType, ctx, {
             ...params,
@@ -468,7 +557,7 @@ export const recordProcessor = (schema, ctx, _json, params) => {
     if (keyValues && !def.partial && !omittableOnInput) {
         const validKeyValues = [...keyValues].filter((v) => typeof v === "string" || typeof v === "number");
         if (validKeyValues.length > 0) {
-            json.required = validKeyValues;
+            json.required = validKeyValues.map(String);
         }
     }
 };

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

@@ -47,6 +47,7 @@ function initializeContext(params) {
         cycles: params?.cycles ?? "ref",
         reused: params?.reused ?? "inline",
         intersections: [],
+        deferred: [],
         external: params?.external ?? undefined,
     };
 }
@@ -480,6 +481,8 @@ function finalize(ctx, schema) {
                 compactTypeUnion(entry[1].def ?? entry[1].schema);
             }
         }
+        for (const rewrite of ctx.deferred)
+            rewrite();
         // After flattening, every member that was extracted is a `$ref`, so the fold sees the final shape. A schema that inherits an intersection — through `z.lazy`, or any `ref` chain — holds the same `allOf` array, so fold by array identity to catch every copy.
         if (ctx.intersections.length) {
             const carriers = new Map();

package/v4/core/to-json-schema.d.cts

@@ -115,6 +115,8 @@ export interface ToJSONSchemaContext {
     reused: "ref" | "inline";
     /** The `allOf` array of each intersection encountered during traversal, innermost first. `finalize` folds every emitted object holding one; see `foldIntersection`. */
     intersections: JSONSchema.BaseSchema[][];
+    /** Rewrites a processor deferred to `finalize`, where the flatten has resolved every ref and the union branches are in place. */
+    deferred: (() => void)[];
     external?: {
         registry: $ZodRegistry<{
             id?: string | undefined;

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

@@ -115,6 +115,8 @@ export interface ToJSONSchemaContext {
     reused: "ref" | "inline";
     /** The `allOf` array of each intersection encountered during traversal, innermost first. `finalize` folds every emitted object holding one; see `foldIntersection`. */
     intersections: JSONSchema.BaseSchema[][];
+    /** Rewrites a processor deferred to `finalize`, where the flatten has resolved every ref and the union branches are in place. */
+    deferred: (() => void)[];
     external?: {
         registry: $ZodRegistry<{
             id?: string | undefined;

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

@@ -39,6 +39,7 @@ export function initializeContext(params) {
         cycles: params?.cycles ?? "ref",
         reused: params?.reused ?? "inline",
         intersections: [],
+        deferred: [],
         external: params?.external ?? undefined,
     };
 }
@@ -472,6 +473,8 @@ export function finalize(ctx, schema) {
                 compactTypeUnion(entry[1].def ?? entry[1].schema);
             }
         }
+        for (const rewrite of ctx.deferred)
+            rewrite();
         // After flattening, every member that was extracted is a `$ref`, so the fold sees the final shape. A schema that inherits an intersection — through `z.lazy`, or any `ref` chain — holds the same `allOf` array, so fold by array identity to catch every copy.
         if (ctx.intersections.length) {
             const carriers = new Map();

package/v4/core/versions.cjs

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

package/v4/core/versions.js

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