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 14 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
5c2602ceb8be8941c64bbe5ac7d92cc174ae6f7e Update AI widget
enum validates against values, for object literal & enums (#5386)globalRegistry (#5452)stringToDate safeDecode methods (#5302)zod-to-mongo-schema to ecosystem documentation (#5457)z.record (#5334)Nothing published for this version
0b109c37c6b0b10e3901b56bcccb72e29a0b846f docs(ecosystem): add bupkis to the ecosystem section
eslint-plugin-zod-x (#5261)2bed4b39760d8e4d678203b5c8fcaf24c182fc9f 4.1.11
7ffedd00169d8dc2e7cb7c6d878f29b03e05b3a3 Fix shape caching
a78716d91da7649a61016b81c27f49fd9e79a81e Update zshy
36c4ee354d0c1f47b7311e49f6dd4b7a11de04f5 Switch back to weakmap
0cca351c8b152d7c4113ab7c2a44675efb060677 Fix variable name inconsistency in coercion documentation
api.mdx (#5209)api.mdx (#5207)@traversable/zod and @traversable/zod-test to v4 ecosystem (#5194)Nothing published for this version
Nothing published for this version
Nothing published for this version
530415f927a8f7fa474c96b667efdad6e771ce4d Update docs
3291c61fe4bc893901027ea5d50dfc6274e49caa fix(v4): toJSONSchema - wrong tuple with null output when targeting openapi-3.0
null output when targeting openapi-3.0 (#5156)validateOpenAPI30Schema in all relevant scenarios (#5163)98ff675c313c15d3fa18b2bd01f844b1e817ee79 Drop stringToBoolean
openapi-3.0 (#5141)openapi-3.0 (#5139)LooseDog instead of Dog (#5136)e45e61b675baf055f4a3ef2ddead21715a1e4fe3 Improve codec docs
openapi-3.0 (#5145)648eb43c23e31f7d69ef09baba46aef4e9493b13 Remove codecs from sidebare
The first minor version since the introduction of Zod 4 back in May. This version contains a number of features that barely missed the cut for the 4.0
The first minor version since the introduction of Zod 4 back in May. This version contains a number of features that barely missed the cut for the 4.0 release. With Zod 4 stable and widely adopted, there's more time to resume feature development.
This is the flagship feature of this release. Codecs are a new API & schema type that encapsulates a bi-directional transformation. It's a huge missing piece in Zod that's finally filled, and it unlocks some totally new ways to use Zod.
const stringToDate = z.codec(
z.iso.datetime(), // input schema: ISO date string
z.date(), // output schema: Date object
{
decode: (isoString) => new Date(isoString),
encode: (date) => date.toISOString(),
}
);
New top-level functions are added for processing inputs in the forward direction ("decoding") and backward direction ("encoding").
stringToDate.decode("2025-08-21T20:59:45.500Z")
// => Date
stringToDate.encode(new Date())
// => "2025-08-21T20:59:45.500Z"
Note — For bundle size reasons, these new methods have not added to Zod Mini schemas. Instead, this functionality is available via equivalent top-level functions.
// equivalent at runtime z.decode(stringToDate, "2024-01-15T10:30:00.000Z"); z.encode(stringToDate, new Date());
.parse() vs .decode()Both .parse() and decode() process data in the "forward" direction. They behave identically at runtime.
stringToDate.parse("2025-08-21T20:59:45.500Z");
stringToDate.decode("2025-08-21T20:59:45.500Z");
There is an important difference however. While .parse() accepts any input, .decode() expects a strongly typed input. That is, it expects an input of type string, whereas .parse() accepts unknown.
stringToDate.parse(Symbol('not-a-string'));
// => fails at runtime, but no TypeScript error
stringToDate.decode(Symbol("not-a-string"));
// ^ ❌ Argument of type 'symbol' is not assignable to parameter of type 'Date'. ts(2345)
This is a highly requested feature unto itself:
- #3860
- #1748
- #3978
- #1892
You can use any Zod schema with .encode(). The vast majority of Zod schemas are non-transforming (the input and output types are identical) so .decode() and .encode() behave identically. Only certain schema types change their behavior:
B->A and executes the encode transform during encodingB->A instead of A->BNote — To avoid increasing bundle size unnecessarily, these new methods are not available on Zod Mini schemas. For those schemas, equivalent top-level functions are provided.
The usual async and safe variants exist as well:
// decode methods
stringToDate.decode("2024-01-15T10:30:00.000Z")
await stringToDate.decodeAsync("2024-01-15T10:30:00.000Z")
stringToDate.safeDecode("2024-01-15T10:30:00.000Z")
await stringToDate.safeDecodeAsync("2024-01-15T10:30:00.000Z")
// encode methods
stringToDate.encode(new Date())
await stringToDate.encodeAsync(new Date())
stringToDate.safeEncode(new Date())
await stringToDate.safeEncodeAsync(new Date())
Below are some "worked examples" for some commonly-needed codecs. These examples are all tested internally for correctness. Just copy/paste them into your project as needed. There is a more comprehensive set available at zod.dev/codecs.
stringToBigIntConverts bigint into a serializable form.
const stringToBigInt = z.codec(z.string(), z.bigint(), {
decode: (str) => BigInt(str),
encode: (bigint) => bigint.toString(),
});
stringToBigInt.decode("12345"); // => 12345n
stringToBigInt.encode(12345n); // => "12345"
jsonParses/stringifies JSON data.
const jsonCodec = z.codec(z.string(), z.json(), {
decode: (jsonString, ctx) => {
try {
return JSON.parse(jsonString);
} catch (err: any) {
ctx.issues.push({
code: "invalid_format",
format: "json_string",
input: jsonString,
message: err.message,
});
return z.NEVER;
}
},
encode: (value) => JSON.stringify(value),
});
To further validate the data, .pipe() the result of this codec into another schema.
const Params = z.object({ name: z.string(), age: z.number() });
const JsonToParams = jsonCodec.pipe(Params);
JsonToParams.decode('{"name":"Alice","age":30}'); // => { name: "Alice", age: 30 }
JsonToParams.encode({ name: "Bob", age: 25 }); // => '{"name":"Bob","age":25}'
For more examples and a technical breakdown of how encoding works, reads theannouncement blog post and new Codecs docs page. The docs page contains implementations for several other commonly-needed codecs:
stringToNumberstringToIntstringToBigIntnumberToBigIntisoDatetimeToDateepochSecondsToDateepochMillisToDatejsonCodecutf8ToBytesbytesToUtf8base64ToBytesbase64urlToByteshexToBytesstringToURLstringToHttpURLuriComponentstringToBoolean.safeExtend()The existing way to add additional fields to an object is to use .extend().
const A = z.object({ a: z.string() })
const B = A.extend({ b: z.string() })
Unfortunately this is a bit of a misnomer, as it allows you to overwrite existing fields. This means the result of .extend() may not literally extend the original type (in the TypeScript sense).
const A = z.object({ a: z.string() }) // { a: string }
const B = A.extend({ a: z.number() }) // { a: number }
To enforce true extends logic, Zod 4.1 introduces a new .safeExtend() method. This statically enforces that the newly added properties conform to the existing ones.
z.object({ a: z.string() }).safeExtend({ a: z.number().min(5) }); // ✅
z.object({ a: z.string() }).safeExtend({ a: z.any() }); // ✅
z.object({ a: z.string() }).safeExtend({ a: z.number() });
// ^ ❌ ZodNumber is not assignable
Importantly, this new API allows you to safely extend objects containing refinements.
const AB = z.object({ a: z.string(), b: z.string() }).refine(val => val.a === val.b);
const ABC = AB.safeExtend({ c: z.string() });
// ABC includes the refinements defined on AB
Previously (in Zod 4.x) any refinements attached to the base schema were dropped in the extended result. This was too unexpected. It now throws an error. (Zod 3 did not support extension of refined objects either.)
z.hash()A new top-level string format for validating hashes produced using various common algorithms & encodings.
const md5Schema = z.hash("md5");
// => ZodCustomStringFormat<"md5_hex">
const sha256Base64 = z.hash("sha256", { enc: "base64" });
// => ZodCustomStringFormat<"sha256_base64">
The following hash algorithms and encodings are supported. Each cell provides information about the expected number of characters/padding.
| Algorithm / Encoding | "hex" |
"base64" |
"base64url" |
|---|---|---|---|
"md5" |
32 | 24 (22 + "==") | 22 |
"sha1" |
40 | 28 (27 + "=") | 27 |
"sha256" |
64 | 44 (43 + "=") | 43 |
"sha384" |
96 | 64 (no padding) | 64 |
"sha512" |
128 | 88 (86 + "==") | 86 |
z.hex()To validate hexadecimal strings of any length.
const hexSchema = z.hex();
hexSchema.parse("123abc"); // ✅ "123abc"
hexSchema.parse("DEADBEEF"); // ✅ "DEADBEEF"
hexSchema.parse("xyz"); // ❌ ZodError
FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF) per the RFC$ZodFunction is now a subtype of $ZodTypeNothing 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
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
1cebf336c560c87e6f806b9d02106fb623049f21 Add blog
d589186c20c3dc112f5a5fda23cccd4d1f74420e fix: ensure keyof returns enum
edit this page button, now redirects to correct url using the new path (#5056)7e7e3461aceecf3633e158df50d6bc852e7cdf45 Clean up docs
99391a844271558e0f1736c9550375e82e630bbd Docs: Fix typo
362eb33093e9c5f306eeec95e36985a99aba8fc7 Fix optional + pipe handling. Closes #5002. v4.0.13
Your coding agent can read these notes before it upgrades. Set up the MCP server →