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:
{
"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 #5758: apply description and default metadata in
fromJSONSchema().
- Closed #5731 via #5759: strip redundant
id from $defs entries in JSON Schema output.
- Closed #5605 via #5763: update
z.custom() docs for v4 compatibility.
- Closed #5593 via #5769: support
discriminatedUnion().encode() with codec discriminators.
- Closed #5625 via #5770: add codec inversion.
- Closed #5778 via #5779: add custom docs 404 page.
- Closed #5792 via #5793: correct floating-point
multipleOf() validation.
- Closed #5777 via #5797: resolve recursive lazy JSON Schema stack overflow.
- Closed #5805 via #5812: fix self-referencing schema docs.
- Closed #5826 via #5855: clone
Map and Set defaults.
- Closed #5842 via #5856: align
.merge() refinement semantics with .extend().
- Closed #4461 and #5414 via #5864: honor
jitless config in the eval probe.
- Closed #5868 via #5869: handle empty
z.union([]) and z.xor([]).
- Closed #5296 via #5891: apply key schema transforms in
z.record().
- Closed #5824 via #5893: emit falsy prefault values in JSON Schema output.
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
eaa3c2c3 Update positive checks to use alias .gt(0) in the docs (#5671) by @Fredkiss3
- Commit
65f1f404 fix typo (#5676) by @Nikita0x
- Commit
5b574501 fix: respect abort: true in .refine() for checks with when function (#5681)
- Commit
539de140 docs: fix README links for async refinements/transforms (#5682) by @pavan-sh
- Commit
46cd10e7 docs: fix README anchor links for async APIs (#5683) by @pavan-sh
- Commit
55747b3c Remove deprecated downlevelIteration option (#5684) by @RyanCavanaugh
- Commit
3a818de1 fix(v4): handle multi-digit exponents in floatSafeRemainder (#5687) by @shakecodeslikecray
- Commit
3cd45ebc fix(v4): add strict validation to httpUrl() (#5672) by @LuckySilver0021
- Commit
7d98c909 add Sanity as silver sponsor and Mintlify as bronze sponsor
- Commit
c7805073 move Sanity and Mintlify to top of sponsor lists
- Commit
bee2dc8d docs: move z.iso.time() from format to pattern section (#5696)
- Commit
2f8414bc fix: add missing addIssue to transform context (#5699) by @F-A-N-D-E
- Commit
d3c0ec87 docs: add note about removed .errors alias in v4 changelog (#5705) by @togami2864
- Commit
fa338a3b fix(v4): JSON schema min/max intersection for draft-04 and openapi-3.0 (#5700) by @ebroder
- Commit
3473b288 chore: bump zshy to ^0.7.1
- Commit
cc8f9b7c docs: improve README wording and fix typos (#5736) by @vedanshshetti
- Commit
f5336717 feat: add json-up to ecosystem (#5740) by @mrspence
- Commit
60ff3987 fix(v4): preserve parent path when treeifying nested union/key/element issues
- Commit
08b14b51 perf: avoid delete in finalizeIssue to keep V8 fast mode (#5718)
- Commit
9cf868d2 fix(v4): treeify error nested union bug (#5708) by @dstashevskyi
- Commit
28f39a6d Add JSONType export (#5709) by @RobinVdBroeck
- Commit
65fab33e feat: allow when parameter in .superRefine() (#5741) by @vilvai
- Commit
7f87df1e refactor(v4): remove unnecessary type assertions (#5720) by @chisaki66
- Commit
518f15dd Preprocess is not deprecated (#5721) by @mxdvl
- Commit
2e5b23dc fix: add options to invalid discriminator errors (#5723) by @Danielchinasa
- Commit
7f789def fix: skip non-enumerable properties in record validation (#5719) by @veeceey
- Commit
ee15fa19 docs: add AGENTS notes for JSDoc, PR comments, and PR worktree workflow
- Commit
f52b4d28 Revert "docs: improve README wording and fix typos (#5736)"
- Commit
ddb41391 test: increase timeout for redos checker in datetime.test.ts (#5744) by @rishadaufa
- Commit
bc07e459 docs: fix doc (#5745) by @xgaia
- Commit
e06af5de Update Hey API description (#5748) by @mrlubos
- Commit
28c156e2 fix: apply description and default metadata to enum, const, and not schemas in fromJSONSchema (#5758) by @mibragimov
- Commit
f457edf1 Fix grammar in CONTRIBUTING.md (#5765) by @siekmang
- Commit
411f6c64 fix(v4): resolve stack overflow in toJSONSchema for recursive lazy with describe (#5797) by @Hassad674
- Commit
45dd421e docs: add tone guidelines for issue and PR comments to AGENTS.md
- Commit
ddd20a30 test: align optional property assertions with actual inferred types
- Commit
a1cf8a93 docs: update z.custom example for v4 compatibility (#5763) by @andrewdamelio
- Commit
b6a3b336 fix: strip redundant id from $defs entries in toJSONSchema (#5759) by @mibragimov
- Commit
c7a8ccc0 fix: discriminatedUnion encode() with codec discriminator (#5769) by @mahmoodhamdi
- Commit
87cf0f93 fix(fromJSONSchema): normalize input via JSON round-trip
- Commit
7163e6f2 feat: add .invert() method to ZodCodec (#5770) by @mahmoodhamdi
- Commit
b59b9b13 fix: replace .default with .prefault (#5776) by @alanskovrlj
- Commit
93bba686 docs: add Zod AOT to ecosystem page (#5806) by @wakita181009
- Commit
2564caa4 fix(docs): add custom 404 page with proper theme support (#5779) by @WolfieLeader
- Commit
5b7ed214 fix: correct multipleOf float validation using tolerance-based comparison (#5793) by @cyphercodes
- Commit
cc9139d2 docs: fix self-referencing schema in refine when() example (#5812) by @claygeo
- Commit
0e960108 fix(v4): support v3-style single-arg z.record(valueType)
- Commit
41b25af9 docs(agents): refine PR comment tone guidance
- Commit
4c03c20d Update Italian locale error messages for validation (#5852) by @pastorello
- Commit
37ac1ba0 fix(fr): translate issue.origin in too_big/too_small errors (#5845) by @Ouaziz-chedli
- Commit
345be203 docs: add validex to ecosystem (#5848) by @chiptoma
- Commit
3c1f32bd feat(locales/en): handle instanceof and add comprehensive locale tests
- Commit
888e52bb feat(locales): add Greek (el) locale (#5840) by @saileshbro
- Commit
bf6d99ed Revert "feat(locales/en): handle instanceof and add comprehensive locale tests"
- Commit
e8196a8d fix(resolution): align expected fr message with translated locale
- Commit
b6b12882 correct logic for validating length (#5843) by @nameearly
- Commit
34f60159 fix(v4): clone Map and Set in shallowClone to prevent shared state across .default() parses (#5855) by @artur-seppa
- Commit
91a7d0d1 fix(v4): reject whitespace in z.base64() to close atob bypass
- Commit
23edf484 Revert "fix(v4): reject whitespace in z.base64() to close atob bypass"
- Commit
15cafa13 fix(v4): throw on .merge() receiver with refinements; preserve refinements from second schema (#5856) by @solssak
- Commit
584b1089 fix(v4): reject whitespace in z.base64() to close atob bypass (#5888) by @colinhacks
- Commit
b9b62c65 fix(core): honour jitless config in allowsEval probe (#5864) by @dokson
- Commit
fffe99bd fix(v4): construct empty unions instead of crashing (#5869) by @tjenkinson
- Commit
285bde7f feat(core): share globalConfig across module systems via globalThis (#5889) by @colinhacks
- Commit
195e8696 perf(v4): mark top-level factory calls as /*@__PURE__*/ for tree-shaking
- Commit
61d7bedb fix(v4): apply key schema transforms in z.record() (#5891) by @colinhacks
- Commit
45acd2ad ci(release): switch to npm trusted publishing via OIDC (#5890) by @colinhacks
- Commit
476ae243 Tighten cuid() regex and deprecate CUID v1 (#5880) by @colinhacks
- Commit
6217527e docs(agents): document push-to-main footgun and version-bump rule (#5883) by @colinhacks
- Commit
757f0b0f fix(v4): apply util.Writeable in strictObject/looseObject for shape display parity (#5882) by @colinhacks
- Commit
fa4a3740 fix(v4): apply util.Writeable in mini object constructors and extend/safeExtend/partial/required (#5895) by @colinhacks
- Commit
ebc8287c fix(v4): emit falsy prefault values in toJSONSchema (#5893) by @mixelburg
- Commit
8fcb71a5 perf(v4): lazy-bind builder methods to shared internal prototype (#5897) by @colinhacks
- Commit
76e8f706 fix(v4): skip __proto__ key in object catchall (#5898) by @colinhacks
- Commit
f0b0608e ecosystem: eslint-plugin-zod-x is eslint-plugin-zod now (#5637) by @marcalexiei
- Commit
0b5c3bc2 docs: fix refinements examples in api.mdx (#5649) by @playoffthecuff
- Commit
327e152e docs(agents): refine PR comment tone guidance further
- Commit
57d80a82 test(v4): pin object/tuple key optionality through optout propagation
- Commit
f19860f1 fix: preserve context immutability in parse functions (#5632) by @bgk614
- Commit
ec979ad7 feat: add Romanian (ro) locale (#5657) by @tushargr0ver
- Commit
b6066b3e fix(v4): align object and tuple optionality handling (#5661) by @Cyjin-jani
- Commit
ad0b8271 ci: update release workflow for trusted publishing
- Commit
6db607be fix(release): keep JSR manifest publishable
- Commit
f778e02a build: bump zshy for JSR wildcard exports