zod

4.4.0

This is a minor release with a wide set of correctness and soundness fixes. Some fixes intentionally make Zod stricter, so code that depended on previously accepted invalid or ambiguous inputs may need small updates.

Potentially breaking bug fixes

Tuple defaults now materialize output values correctly

Fixed in #5661. Tuple parsing now more accurately reflects defaults, optional tails, explicit undefined, and under-filled inputs. The headline behavior is that defaults in tuple positions now properly appear in parsed output.

const schema = z.tuple([
  z.string(),
  z.string().default("fallback"),
]);

schema.parse(["a"]);
// ["a", "fallback"]

Trailing optional elements that are absent still stay absent; they are not filled with undefined.

const schema = z.tuple([
  z.string(),
  z.string().optional(),
]);

schema.parse(["a"]);
// ["a"]

But explicit undefined values supplied by the caller are preserved.

schema.parse(["a", undefined]);
// ["a", undefined]

When optional elements appear before later defaults, the parsed tuple is now dense so array operations behave predictably.

const schema = z.tuple([
  z.string(),
  z.string().optional(),
  z.string().default("fallback"),
]);

schema.parse(["a"]);
// ["a", undefined, "fallback"]

Tuple length errors are also more consistent now. Since z.function() arguments are tuple-shaped, function input errors may look different.

Required object properties with z.undefined()

Fixed in #5661, with follow-up coverage in 57d80a82. A property whose schema is z.undefined() is now treated as required. The key must be present, but its value may be undefined.

const schema = z.object({
  value: z.undefined(),
});

schema.safeParse({}).success;
// false

schema.safeParse({ value: undefined }).success;
// true

Use .optional() when the key itself may be absent.

const schema = z.object({
  value: z.undefined().optional(),
});

schema.safeParse({}).success;
// true

This also affects related .catch(), .partial(), .default(), and .prefault() combinations that previously relied on missing z.undefined() keys being treated as optional.

Safer .merge() behavior with refinements

Fixed in #5856. The .merge() method now throws when the receiver has refinements, rather than silently producing ambiguous refinement behavior. Refinements from the second schema are preserved.

const a = z.object({ a: z.string() }).refine((val) => val.a.length > 0);
const b = z.object({ b: z.string() });

a.merge(b);
// throws

Prefer .extend() or .safeExtend() for object composition. The .merge() method is still supported for compatibility, but it is discouraged for new code because its semantics around overlapping keys and refinements are easier to misread.

JSON Schema $defs entries no longer include redundant id

Fixed in #5759. JSON Schema conversion through z.toJSONSchema() now strips redundant id fields from $defs entries. This is required for correctness in older JSON Schema dialects from before $id was introduced: in those dialects, id changes the resolution scope, so leaving it inside an extracted definition can make references resolve incorrectly. The removed value was redundant because the schema had already been extracted into $defs, so the definition key itself is the identifier. This may affect consumers that were reading those internal id fields directly.

Other JSON Schema fixes in this release:

• Draft-04/OpenAPI 3.0 min/max intersections: #5700
• Recursive lazy schemas with .describe(): #5797
• Falsy prefault values emitted as defaults: #5893
• CUID pattern output tightened: #5880

String validators are stricter

Base64 validation now rejects whitespace instead of allowing atob()-style whitespace stripping. Fixed in #5888.

z.base64().safeParse("Zm9v").success;
// true

z.base64().safeParse("Zm 9v").success;
// false

Other string validator changes:

• CUID validation through z.cuid() has been tightened, and CUID v1 is now deprecated. Fixed in #5880.
• HTTP URL validation through z.httpUrl() now rejects malformed HTTP(S) URLs with a missing slash after the protocol. The underlying URL constructor normalizes inputs like https:/example.com, but Zod now rejects them instead of accepting the repaired URL. Fixed in #5672, related to #5284.

z.httpUrl().safeParse("https://example.com").success;
// true

z.httpUrl().safeParse("https:/example.com").success;
// false

z.httpUrl().safeParse("http:/www.apple.com").success;
// false

Union paths are fixed in formatted errors

Two union-related error fixes landed:

• Nested union paths are now preserved correctly in the output of z.treeifyError() and z.formatError(). Fixed in #5708 and 60ff3987.
• Invalid discriminated union errors now include discriminator options and improved messages. Fixed in #5723. This may affect users snapshotting ZodError output.

Other fixes

Record key transforms now run

Fixed in #5891. Record schemas now run transforms on record keys.

const schema = z.record(
  z.string().transform((key) => key.toUpperCase()),
  z.number()
);

schema.parse({ foo: 1 });
// { FOO: 1 }

Related record fixes:

• Key refinement failures now surface as structured invalid_key issues. Fixed in #5719.
• Non-enumerable properties are skipped more consistently. Fixed in #5719.
• The v3-style single-argument z.record(valueType) form works again. Fixed in 0e960108.

Metadata and input handling in fromJSONSchema()

Schema generation from JSON Schema now applies metadata more consistently across enum, const, not, anyOf, and multi-type schemas. Fixed in #5758. It also rejects or normalizes more non-JSON-like inputs, including cyclic objects and BigInt. Fixed in 87cf0f93.

Codecs

Codec changes:

• Encoding through z.discriminatedUnion().encode() now works when the discriminator uses a codec. Fixed in #5769.
• Codec inversion was added in #5770.

const stringToNumber = z.codec(
  z.string(),
  z.number(),
  {
    decode: Number,
    encode: String,
  }
);

const numberToString = z.invertCodec(stringToNumber);

Transform context

Transform callbacks now support ctx.addIssue(). Fixed in #5699.

Conditional .superRefine() with when

The when option was added for .superRefine(). Added in #5741, with related abort behavior fixed in #5681.

Defaults for Map and Set

Defaults for Map and Set are now cloned instead of shared across parses. Fixed in #5855.

const schema = z.map(z.string(), z.number()).default(new Map());

const a = schema.parse(undefined);
const b = schema.parse(undefined);

a === b;
// false

Empty unions

Empty z.union([]), z.xor([]), and discriminated unions no longer crash at construction time. They construct and fail at parse time. Fixed in #5869.

Floating-point multiples

Number multipleOf() / step() validation is more accurate for decimal and exponent edge cases. Fixed in #5687 and #5793.

Global config and jitless

Configuration fixes:

• Global configuration is now shared through globalThis, improving behavior across mixed CJS/ESM module instances. Fixed in #5889.
• Jitless mode now avoids eval probing when set before first access. Fixed in #5864.

Prototype pollution hardening

Object catchall paths now skip __proto__ keys. Fixed in #5898.

Performance improvements

Reduced memory usage from lazy-bound methods

Fixed in #5897. Classic builder methods are now lazy-bound through a shared internal prototype instead of eagerly attached per schema instance. This significantly reduces per-schema method allocation overhead, especially in codebases that construct many schemas. Detached methods continue to work:

const schema = z.string();
const optional = schema.optional;

optional.call(schema);
// still works

Improved tree-shaking

Implemented in 195e8696 and #5689. Top-level factory calls are annotated as pure, and generated stub package manifests now include sideEffects: false. This gives bundlers more room to remove unused Zod code.

This is intended as the conclusive fix for a long-standing class of tree-shaking and bundle-size issues, especially in Next.js and Turbopack projects. The most visible symptom was that unused validators and locales could survive bundling even when importing from zod/mini or from a narrow subpath.

Related reports include:

• Next.js and Turbopack tree-shaking reports: #4433, #5641, #5095, #4810
• Locale and zod/mini bundle-size reports: #5561, #5665, #4369, #4572
• Broader v4 bundle-size reports: #2596, #4637, #4798, #5206

{
  "sideEffects": false
}

Locales

Added or updated locale support:

• Croatian: #5610
• Greek: #5840
• Romanian: #5657
• Uzbek map support: #5599
• Georgian translation fix: #5655
• French issue origin translations: #5845
• Italian validation message updates: #5852

Locale message text changed in some cases, which may affect snapshots.

Closed issues

The following issues were closed by PRs included in this release:

• Closed #5466 via #5632: preserve context immutability in parse functions.
• Closed #5617 via #5655: correct Georgian translation for string.
• Closed #5619 via #5657: add Romanian locale.
• Closed #5229 via #5661: align object and tuple optionality handling.
• Closed #5680 via #5681: respect abort: true in .refine() checks with when.
• Closed #5678 via #5699: add missing addIssue to transform context.
• Closed #5717 via #5718: avoid delete in finalizeIssue.
• Closed #5714 via #5719: skip non-enumerable properties in record validation.
• Closed #5670 via #5723: add discriminator options to invalid discriminator errors.
• Closed #5743 via #5744: increase timeout for the datetime ReDoS checker test.
• Closed #5732 via : apply description and default metadata in .

Commits

• Commit 44f6a03e fix(locales): correct Georgian translation for 'string' to 'ველი' (#5655) by @tushargr0ver
• Commit 7b43bc64 docs(ecosystem): add Hono Takibi (#5651) by @nakita628
• Commit 119376b9 feat: add map support to Uzbek locale (#5599) by @uchkunr
• Commit 8fbf701e test: add edge case tests for boundary values (#5601) by @uchkunr
• Commit f1f93c2b Fix order of brand method examples in api.mdx (#5604) by @onurtemiz
• Commit 10105ee4 docs: Fix typos in json-schema documentation (#5608) by @SaKaNa-Y
• Commit 2d367139 feat: add hr translation (#5610) by @vuki656
• Commit 54902cb7 chore: update pullfrog.yml workflow
• Commit 89ba70f2 chore: add sideEffects false to stub package.json for tree-shaking (#5689) by @jesse-holden
• Commit Update positive checks to use alias in the docs () by @Fredkiss3