NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #423 most downloaded on npm
TypeScript-first schema declaration and validation library with static type inference
Last release 12 days ago
13 Sep 2026
Ships unpredictably
gaps range from 8 days to 3 months
Nearly every release is documented
notes for 57 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
1011 releases · first in 2020
One column per quarter.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
4c2fa95 docs: use Zernio primary wordmark for gold sponsor logo
88015df fix(docs): drop deprecated baseUrl from tsconfig
baseUrl from tsconfig481f7be ci: gate release publishing on full test workflow
CUID validation through z.cuid() has been tightened, and CUID v1 is now deprecated. Fixed in #5880 .
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.
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.
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;
// trueUse .optional() when the key itself may be absent.
const schema = z.object({
value: z.undefined().optional(),
});
schema.safeParse({}).success;
// trueThis also affects related .catch(), .partial(), .default(), and .prefault() combinations that previously relied on missing z.undefined() keys being treated as optional.
.merge() behavior with refinementsFixed 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);
// throwsPrefer
.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.
$defs entries no longer include redundant idFixed 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:
.describe(): #5797Base64 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;
// falseOther string validator changes:
z.cuid() has been tightened, and CUID v1 is now deprecated. Fixed in #5880.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;
// falseTwo union-related error fixes landed:
z.treeifyError() and z.formatError(). Fixed in #5708 and 60ff3987.ZodError output.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:
invalid_key issues. Fixed in #5719.z.record(valueType) form works again. Fixed in 0e960108.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.
Codec changes:
z.discriminatedUnion().encode() now works when the discriminator uses a codec. Fixed in #5769.const stringToNumber = z.codec(
z.string(),
z.number(),
{
decode: Number,
encode: String,
}
);
const numberToString = z.invertCodec(stringToNumber);Transform callbacks now support ctx.addIssue(). Fixed in #5699.
.superRefine() with whenThe when option was added for .superRefine(). Added in #5741, with related abort behavior fixed in #5681.
Map and SetDefaults 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;
// falseEmpty z.union([]), z.xor([]), and discriminated unions no longer crash at construction time. They construct and fail at parse time. Fixed in #5869.
Number multipleOf() / step() validation is more accurate for decimal and exponent edge cases. Fixed in #5687 and #5793.
jitlessConfiguration fixes:
globalThis, improving behavior across mixed CJS/ESM module instances. Fixed in #5889.Object catchall paths now skip __proto__ keys. Fixed in #5898.
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 worksImplemented 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:
zod/mini bundle-size reports: #5561, #5665, #4369, #4572{
"sideEffects": false
}Added or updated locale support:
Locale message text changed in some cases, which may affect snapshots.
The following issues were closed by PRs included in this release:
string.abort: true in .refine() checks with when.addIssue to transform context.delete in finalizeIssue.options to invalid discriminator errors.fromJSONSchema().id from $defs entries in JSON Schema output.z.custom() docs for v4 compatibility.discriminatedUnion().encode() with codec discriminators.multipleOf() validation.Map and Set defaults..merge() refinement semantics with .extend().jitless config in the eval probe.z.union([]) and z.xor([]).z.record().44f6a03e fix(locales): correct Georgian translation for 'string' to 'ველი' (#5655) by @tushargr0ver7b43bc64 docs(ecosystem): add Hono Takibi (#5651) by @nakita628119376b9 feat: add map support to Uzbek locale (#5599) by @uchkunr8fbf701e test: add edge case tests for boundary values (#5601) by @uchkunrf1f93c2b Fix order of brand method examples in api.mdx (#5604) by @onurtemiz10105ee4 docs: Fix typos in json-schema documentation (#5608) by @SaKaNa-Y2d367139 feat: add hr translation (#5610) by @vuki65654902cb7 chore: update pullfrog.yml workflow89ba70f2 chore: add sideEffects false to stub package.json for tree-shaking (#5689) by @jesse-holdeneaa3c2c3 Update positive checks to use alias .gt(0) in the docs (#5671) by @Fredkiss365f1f404 fix typo (#5676) by @Nikita0x5b574501 fix: respect abort: true in .refine() for checks with when function (#5681)539de140 docs: fix README links for async refinements/transforms (#5682) by @pavan-sh46cd10e7 docs: fix README anchor links for async APIs (#5683) by @pavan-sh55747b3c Remove deprecated downlevelIteration option (#5684) by @RyanCavanaugh3a818de1 fix(v4): handle multi-digit exponents in floatSafeRemainder (#5687) by @shakecodeslikecray3cd45ebc fix(v4): add strict validation to httpUrl() (#5672) by @LuckySilver00217d98c909 add Sanity as silver sponsor and Mintlify as bronze sponsorc7805073 move Sanity and Mintlify to top of sponsor listsbee2dc8d docs: move z.iso.time() from format to pattern section (#5696)2f8414bc fix: add missing addIssue to transform context (#5699) by @F-A-N-D-Ed3c0ec87 docs: add note about removed .errors alias in v4 changelog (#5705) by @togami2864fa338a3b fix(v4): JSON schema min/max intersection for draft-04 and openapi-3.0 (#5700) by @ebroder3473b288 chore: bump zshy to ^0.7.1cc8f9b7c docs: improve README wording and fix typos (#5736) by @vedanshshettif5336717 feat: add json-up to ecosystem (#5740) by @mrspence60ff3987 fix(v4): preserve parent path when treeifying nested union/key/element issues08b14b51 perf: avoid delete in finalizeIssue to keep V8 fast mode (#5718)9cf868d2 fix(v4): treeify error nested union bug (#5708) by @dstashevskyi28f39a6d Add JSONType export (#5709) by @RobinVdBroeck65fab33e feat: allow when parameter in .superRefine() (#5741) by @vilvai7f87df1e refactor(v4): remove unnecessary type assertions (#5720) by @chisaki66518f15dd Preprocess is not deprecated (#5721) by @mxdvl2e5b23dc fix: add options to invalid discriminator errors (#5723) by @Danielchinasa7f789def fix: skip non-enumerable properties in record validation (#5719) by @veeceeyee15fa19 docs: add AGENTS notes for JSDoc, PR comments, and PR worktree workflowf52b4d28 Revert "docs: improve README wording and fix typos (#5736)"ddb41391 test: increase timeout for redos checker in datetime.test.ts (#5744) by @rishadaufabc07e459 docs: fix doc (#5745) by @xgaiae06af5de Update Hey API description (#5748) by @mrlubos28c156e2 fix: apply description and default metadata to enum, const, and not schemas in fromJSONSchema (#5758) by @mibragimovf457edf1 Fix grammar in CONTRIBUTING.md (#5765) by @siekmang411f6c64 fix(v4): resolve stack overflow in toJSONSchema for recursive lazy with describe (#5797) by @Hassad67445dd421e docs: add tone guidelines for issue and PR comments to AGENTS.mdddd20a30 test: align optional property assertions with actual inferred typesa1cf8a93 docs: update z.custom example for v4 compatibility (#5763) by @andrewdameliob6a3b336 fix: strip redundant id from $defs entries in toJSONSchema (#5759) by @mibragimovc7a8ccc0 fix: discriminatedUnion encode() with codec discriminator (#5769) by @mahmoodhamdi87cf0f93 fix(fromJSONSchema): normalize input via JSON round-trip7163e6f2 feat: add .invert() method to ZodCodec (#5770) by @mahmoodhamdib59b9b13 fix: replace .default with .prefault (#5776) by @alanskovrlj93bba686 docs: add Zod AOT to ecosystem page (#5806) by @wakita1810092564caa4 fix(docs): add custom 404 page with proper theme support (#5779) by @WolfieLeader5b7ed214 fix: correct multipleOf float validation using tolerance-based comparison (#5793) by @cyphercodescc9139d2 docs: fix self-referencing schema in refine when() example (#5812) by @claygeo0e960108 fix(v4): support v3-style single-arg z.record(valueType)41b25af9 docs(agents): refine PR comment tone guidance4c03c20d Update Italian locale error messages for validation (#5852) by @pastorello37ac1ba0 fix(fr): translate issue.origin in too_big/too_small errors (#5845) by @Ouaziz-chedli345be203 docs: add validex to ecosystem (#5848) by @chiptoma3c1f32bd feat(locales/en): handle instanceof and add comprehensive locale tests888e52bb feat(locales): add Greek (el) locale (#5840) by @saileshbrobf6d99ed Revert "feat(locales/en): handle instanceof and add comprehensive locale tests"e8196a8d fix(resolution): align expected fr message with translated localeb6b12882 correct logic for validating length (#5843) by @nameearly34f60159 fix(v4): clone Map and Set in shallowClone to prevent shared state across .default() parses (#5855) by @artur-seppa91a7d0d1 fix(v4): reject whitespace in z.base64() to close atob bypass23edf484 Revert "fix(v4): reject whitespace in z.base64() to close atob bypass"15cafa13 fix(v4): throw on .merge() receiver with refinements; preserve refinements from second schema (#5856) by @solssak584b1089 fix(v4): reject whitespace in z.base64() to close atob bypass (#5888) by Note truncated.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
9977fb0 Add brand.dev to sponsors
21afffd [Docs] Update migration guide docs for deprecation of message
e01cd02 Support patternProperties for looserecord
Commits: f3b2151 v4.3.3
0fe8840 allow non-overwriting extends with refinements. 4.3.1
// add arbitrary metadata const schema2 = z.number().with( z.meta({ deprecated: true }) ); ```
This is Zod's biggest release since 4.0. It addresses several of Zod's longest-standing feature requests.
z.fromJSONSchema()Convert JSON Schema to Zod (#5534, #5586)
You can now convert JSON Schema definitions directly into Zod schemas. This function supports JSON Schema "draft-2020-12", "draft-7", "draft-4", and OpenAPI 3.0.
import * as z from "zod";
const schema = z.fromJSONSchema({
type: "object",
properties: {
name: { type: "string", minLength: 1 },
age: { type: "integer", minimum: 0 },
},
required: ["name"],
});
schema.parse({ name: "Alice", age: 30 }); // ✅
The API should be considered experimental. There are no guarantees of 1:1 "round-trip soundness": MySchema > z.toJSONSchema() > z.fromJSONSchema(). There are several features of Zod that don't exist in JSON Schema and vice versa, which makes this virtually impossible.
Features supported:
string, number, integer, boolean, null, object, array)email, uri, uuid, date-time, date, time, ipv4, ipv6, and more)anyOf, oneOf, allOf)additionalProperties, patternProperties, propertyNames)prefixItems, items, minItems, maxItems)$ref for local references and circular schemasz.xor() — exclusive union (#5534)A new exclusive union type that requires exactly one option to match. Unlike z.union() which passes if any option matches, z.xor() fails if zero or more than one option matches.
const schema = z.xor([z.string(), z.number()]);
schema.parse("hello"); // ✅
schema.parse(42); // ✅
schema.parse(true); // ❌ zero matches
When converted to JSON Schema, z.xor() produces oneOf instead of anyOf.
z.looseRecord() — partial record validation (#5534)A new record variant that only validates keys matching the key schema, passing through non-matching keys unchanged. This is used to represent patternProperties in JSON Schema.
const schema = z.looseRecord(z.string().regex(/^S_/), z.string());
schema.parse({ S_name: "John", other: 123 });
// ✅ { S_name: "John", other: 123 }
// only S_name is validated, "other" passes through
.exactOptional() — strict optional properties (#5589)A new wrapper that makes a property key-optional (can be omitted) but does not accept undefined as an explicit value.
const schema = z.object({
a: z.string().optional(), // accepts `undefined`
b: z.string().exactOptional(), // does not accept `undefined`
});
schema.parse({}); // ✅
schema.parse({ a: undefined }); // ✅
schema.parse({ b: undefined }); // ❌
This makes it possible to accurately represent the full spectrum of optionality expressible using exactOptionalPropertyTypes.
.apply()A utility method for applying arbitrary transformations to a schema, enabling cleaner schema composition. (#5463)
const setCommonChecks = <T extends z.ZodNumber>(schema: T) => {
return schema.min(0).max(100);
};
const schema = z.number().apply(setCommonChecks).nullable();
.brand() cardinalityThe .brand() method now accepts a second argument to control whether the brand applies to input, output, or both. Closes #4764, #4836.
// output only (default)
z.string().brand<"UserId">(); // output is branded (default)
z.string().brand<"UserId", "out">(); // output is branded
z.string().brand<"UserId", "in">(); // input is branded
z.string().brand<"UserId", "inout">(); // both are branded
.refine() (#5575)The .refine() method now supports type predicates to narrow the output type:
const schema = z.string().refine((s): s is "a" => s === "a");
type Input = z.input<typeof schema>; // string
type Output = z.output<typeof schema>; // "a"
ZodMap methods: min, max, nonempty, size (#5316)ZodMap now has parity with ZodSet and ZodArray:
const schema = z.map(z.string(), z.number())
.min(1)
.max(10)
.nonempty();
schema.size; // access the size constraint
.with() alias for .check() (359c0db)A new .with() method has been added as a more readable alias for .check(). Over time, more APIs have been added that don't qualify as "checks". The new method provides a readable alternative that doesn't muddy semantics.
z.string().with(
z.minLength(5),
z.toLowerCase()
);
// equivalent to:
z.string().check(
z.minLength(5),
z.trim(),
z.toLowerCase()
);
z.slugify() transformTransform strings into URL-friendly slugs. Works great with .with():
// Zod
z.string().slugify().parse("Hello World"); // "hello-world"
// Zod Mini
// using .with() for explicit check composition
z.string().with(z.slugify()).parse("Hello World"); // "hello-world"
z.meta() and z.describe() in Zod Mini (947b4eb)Zod Mini now exports z.meta() and z.describe() as top-level functions for adding metadata to schemas:
import * as z from "zod/mini";
// add description
const schema = z.string().with(
z.describe("A user's name"),
);
// add arbitrary metadata
const schema2 = z.number().with(
z.meta({ deprecated: true })
);
When intersecting schemas that include z.strictObject(), Zod 4 now only rejects keys that are unrecognized by both sides of the intersection. Previously, any unrecognized key from either side would cause an error.
This means keys that are recognized by at least one side of the intersection will now pass validation:
const A = z.strictObject({ a: z.string() });
const B = z.object({ b: z.string() });
const C = z.intersection(A, B);
// Keys recognized by either side now work
C.parse({ a: "foo", b: "bar" }); // ✅ { a: "foo", b: "bar" }
// Extra keys are stripped (follows strip behavior from B)
C.parse({ a: "foo", b: "bar", c: "extra" }); // ✅ { a: "foo", b: "bar" }
When both sides are strict, only keys unrecognized by both sides will error:
const A = z.strictObject({ a: z.string() });
const B = z.strictObject({ b: z.string() });
const C = z.intersection(A, B);
// Keys recognized by either side work
C.parse({ a: "foo", b: "bar" }); // ✅
// Keys unrecognized by BOTH sides error
C.parse({ a: "foo", b: "bar", c: "extra" });
// ❌ ZodError: Unrecognized key: "c"
import * as z from "zod";
import { uz } from "zod/locales";
z.config(uz());
<br/><br/><br/>
All of these changes fix soundness issues in Zod. As with any bug fix there's some chance of breakage if you were intentionally or unintentionally relying on this unsound behavior.
.pick() and .omit() disallowed on object schemas containing refinements (#5317)Using .pick() or .omit() on object schemas with refinements now throws an error. Previously, this would silently drop the refinements, leading to unexpected behavior.
const schema = z.object({
password: z.string(),
confirmPassword: z.string(),
}).refine(data => data.password === data.confirmPassword);
schema.pick({ password: true });
// 4.2: refinement silently dropped ⚠️
// 4.3: throws error ❌
Migration: The easiest way to migrate is to create a new schema using the shape of the old one.
const newSchema = z.object(schema.shape).pick({ ... })
.extend() disallowed on object schemas with refinements (#5317)Similarly, .extend() will throws on schemas with refinements if you are overwriting existing properties.
const schema = z.object({
a: z.string()
}).refine(/* ... */);
schema.extend({ a: z.number() }); // 4.3: throws error ❌
Instead you can use .safeExtend(), which statically ensures that you aren't changing the type signature of any pre-existing properties.
const schema = z.object({
a: z.string(),
}).refine(/* ... */);
schema.safeExtend({
a: z.string().min(5).max(10)
}); // ✅ allows overwrite, preserves refinement
Object masking methods (.pick(), .omit()) now validate that the keys provided actually exist in the schema:
const schema = z.object({ a: z.string() });
// 4.3: throws error for unrecognized keys
schema.pick({ nonexistent: true });
// error: unrecognized key: "nonexistent"
<br/><br/><br/>
z.iso.time with minute precision (#5557)includes method params typing to accept string | $ZodCheckIncludesParams (#5556)implementAsync inferred type to always be a promise (#5476)Date instances to numbers in minimum/maximum checks (#5351)z.record() (#5585)~standard schema property (#5363)@__NO_SIDE_EFFECTS__ for better tree-shaking (#5475)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →