v4.1.12

Compare Source

Commits:

• 0b109c3 docs(ecosystem): add bupkis to the ecosystem section (#​5237)
• d22ec0d docs(ecosystem): add upfetch (#​5238)
• c56a4f6 docs(ecosystem): add eslint-plugin-zod-x (#​5261)
• a0abcc0 docs(metadata.mdx): fix a mistake in an example output (#​5248)
• 62bf4e4 fix(ZodError): prevent flatten() from crashing on 'toString' key (#​5266)
• 02a5840 refac(errors): Unify code structure and improve types (#​5278)
• 4b1922a docs(content/v4/index): fix zod version (#​5289)
• 3fcb20f Add frrm to ecosystem (#​5292)
• fda4c7c Make docs work without token
• af44738 Fix lint
• 77c3c9f Export bg.ts
• 3b94610 v4.1.12

v4.1.11

Compare Source

Commits:

• 2bed4b3 4.1.11

v4.1.10

Compare Source

Commits:

• 7ffedd0 Fix shape caching (#​5263)
• 82cd717 v4.1.10

v4.1.9

Compare Source

Commits:

• a78716d Update zshy (#​5249)
• 923af80 Publish zod@​4.1.9

v4.1.8

Compare Source

Commits:

• 36c4ee3 Switch back to weakmap
• a1726d5 4.1.8

v4.1.7

Compare Source

Commits:

• 0cca351 Fix variable name inconsistency in coercion documentation (#​5188)
• aa78c27 Add copy/edit buttons
• 76452d4 Update button txt
• 937f73c Fix tsconfig issue in bench
• 976b436 v4.1.6 (#​5222)
• 4309c61 Fix cidrv6 validation - cidrv6 should reject invalid strings with multiple slashes (#​5196)
• ef95a73 feat(locales): Add Lithuanian (lt) locale (#​5210)
• 3803f3f docs: update wrong contents in codeblocks in api.mdx (#​5209)
• 8a47d5c docs: update coerce example in api.mdx (#​5207)
• e87db13 feat(locales): Add Georgian (ka) locale (#​5203)
• c54b123 docs: adds @traversable/zod and @traversable/zod-test to v4 ecosystem (#​5194)
• c27a294 Fix two tiny grammatical errors in the docs. (#​5193)
• 23a2d66 docs: fix broken links in async refinements and transforms references (#​5190)
• 845a230 fix(locales): Add type name translations to Spanish locale (#​5187)
• 27f13d6 Improve regex precision and eliminate duplicates in regexes.ts (#​5181)
• a8a52b3 fix(v4): fix Khmer and Ukrainian locales (#​5177)
• 887e37c Update slugs
• e1f1948 fix(v4): ensure array defaults are shallow-cloned (#​5173)
• 9f65038 docs(ecosystem): add DRZL; fix Prisma Zod Generator placement (#​5215)
• aa6f0f0 More fixes (#​5223)
• aab3356 4.1.7

v4.1.6

Compare Source

v4.1.5

Compare Source

Commits:

• 530415f Update docs
• b7b081d Update z.function() type to support array input (#​5170)
• 780cf57 4.1.5

v4.1.4

Compare Source

Commits:

• 3291c61 fix(v4): toJSONSchema - wrong tuple with null output when targeting openapi-3.0 (#​5156)
• 23f41c7 test(v4): toJSONSchema - use validateOpenAPI30Schema in all relevant scenarios (#​5163)
• 0a09fd2 Update installation instructions
• 4ea5fec 4.1.4

v4.1.3

Compare Source

Commits:

• 98ff675 Drop stringToBoolean
• a410616 Fix typo
• 0cf4589 fix(v4): toJSONSchema - add missing oneOf inside items in tuple conversion (#​5146)
• 8bf0c16 fix(v4): toJSONSchema tuple path handling for draft-7 with metadata IDs (#​5152)
• 5c5fa90 fix(v4): toJSONSchema - wrong record output when targeting openapi-3.0 (#​5141)
• 87b97cc docs(codecs): update example to use payloadSchema (#​5150)
• 309f358 fix(v4): toJSONSchema - output numbers with exclusive range correctly when targeting openapi-3.0 (#​5139)
• 1e71ca9 docs: fix refine fn to encode works properly (#​5148)
• a85ec3c fix(docs): correct example to use LooseDog instead of Dog (#​5136)
• 3e98274 4.1.3

v4.1.2

Compare Source

Commits:

• e45e61b Improve codec docs
• 25a4c37 fix(v4): toJSONSchema - wrong record tuple output when targeting openapi-3.0 (#​5145)
• 0fa4f46 Use method form in codecs.mdx
• 940383d Update JSON codec and docs
• 3009fa8 4.1.2

v4.1.1

Compare Source

Commits:

• 648eb43 Remove codecs from sidebare
• 7e39a99 Improve codec docs
• e5085be Add images
• 028b289 Add methods
• 10cc994 4.1.1

v4.1.0

Compare Source

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.

Codecs

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

Encoding

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:

• Codecs — runs from B->A and executes the encode transform during encoding
• Pipes — these execute B->A instead of A->B
• Defaults and prefaults — Only applied in the forward direction
• Catch — Only applied in the forward direction

Note — 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())

Example codecs

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.

stringToBigInt

Converts 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"

json

Parses/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}'

Further reading

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:

• stringToNumber
• stringToInt
• stringToBigInt
• numberToBigInt
• isoDatetimeToDate
• epochSecondsToDate
• epochMillisToDate
• jsonCodec
• utf8ToBytes
• bytesToUtf8
• base64ToBytes
• base64urlToBytes
• hexToBytes
• stringToURL
• stringToHttpURL
• uriComponent
• stringToBoolean

.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.

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

Additional changes

1. z.uuid() now supports the "Max UUID" (FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF) per the RFC
2. $ZodFunction is now a subtype of $ZodType

Commits

• edd4fea - Closes #​5127
• 5d4a315 - Closes #​5116
• f3f0955 - Closes #​5108
• 0114d5b - #​5122
• 3b077c3 - #​5121
• 1e06af8 - #​5113
• b01b6f3 — #​5052
• 571ab0c — #​5051
• d3ea111 — #​5049
• b8e3f87 — #​4865

v4.0.17

Compare Source

Commits:

• 1cebf33 Add blog (#​5074)
• fc1e556 Fixes #​5073
• cc63f95 v4.0.17

v4.0.16

Compare Source

Commits:

• d589186 fix: ensure keyof returns enum (#​5045)
• 4975f3a feat: add discriminator generic (#​5044)
• 0a463e3 Update speakeasy files
• 12658af Fix Edit page buttons
• 47e6604 fix: edit this page button, now redirects to correct url using the new path (#​5056)
• 7207a2d Update Hey API link to Zod v3 plugin (#​5060)
• 6887ff3 Update Hey API link to Zod plugin (#​5059)
• ffff1aa Clone POJO objects during defaulting/prefaulting
• a227cb3 v4.0.16

v4.0.15

Compare Source

Commits:

• 7e7e346 Clean up docs
• f2949a8 [docs] Fix migration guide upgrade command (#​5021)
• d43cf19 Fix recursive object initialization errors with check() and other methods (#​5018)
• 3de2b63 fix: remove redundant Required<> from input and output type definitions (#​5033)
• 93553bd Add needs info
• 03cfa8d 4.0.15

v4.0.14

Compare Source

Commits:

• 99391a8 Docs: Fix typo (#​5005)
• e25303e Docs: fix typo (#​5008)
• dbb05ef Add JSON Schema draft-04 output (#​4811)
• b8257d7 Improve tuple recursive inference.
• 9bdbc2f Avoid infinite loops in defineLazy. Fixes #​4994.
• af96ad4 4.0.14

v4.0.13

Compare Source

Commits:

• 362eb33 Fix optional + pipe handling. Closes #​5002. v4.0.13

v4.0.12

Compare Source

Commits:

• ff83fc9 Add eslint-plugin-import-zod (#​4848)
• 7c9ce38 Update docs for z.property check (#​4863)
• c432577 docs: add jwt schema docs (#​4867)
• 35e6a6f Add llms.txt (#​4915)
• 3ac7bf0 Clean up Edit this Page
• 60a9372 Implement llms-full.txt (#​5004)
• 73a1970 4.0.12

v4.0.11

Compare Source

Commits:

• 8e6a5f8 Fix “Edit on Github” link (#​4997)
• 930a2f6 Fix number of errors in doc (#​4993)
• c762dbb feat(locale): Add Yoruba (yo) locale (#​4996)
• 9a34a3a Zod 4.0.11 (#​4981)

v4.0.10

Compare Source

Commits:

• 291c1ca Add should-build script
• e32d99b Move should-build script
• d4faf71 Add v3 docs (#​4972)
• dfae371 Update Jazz img on v3 docs
• d6cd30d fix #​4973 (#​4974)
• 1850496 Fix typo in valype (#​4960)
• 4ec2f87 Add Zod Playground to zod 4 ecosystem (#​4975)
• 2b571a2 Update docs z.enum with object literal example (#​4967)
• 813451d v4.0.10 (#​4978)

v4.0.9

Compare Source

Commits:

• 4e7a3ef v4.0.9 (#​4970)

v4.0.8

Compare Source

Commits:

• 3048d14 Fix #​4961

v4.0.7

Compare Source

Commits:

• 7ab1b3c Do not continue parsing in ZodPipe if issues exists. Closes #​4926.
• 34b400a 4.0.7

v4.0.6

Compare Source

Commits:

• a3e4391 Unwiden catch input type (#​4870)
• 499df78 Add RFC 9562 mentions. Closes #​4872
• d0493f3 Doc tweak - spread vs destructuring (#​4919)
• 8dad394 feat: Icelandic translation (#​4920)
• 2ffdae1 Bulgarian (bg) translation (#​4928)
• 0973135 docs: add valype to xToZodConverts (#​4930)
• d257340 Remove moduleResolution callout (#​4932)
• 075970d docs: add coercion note to fix compile errors (#​4940)
• b9e8a60 Add @hey-api/openapi-ts to Zod 3 ecosystem (#​4949)
• ad7b0ff Add @hey-api/openapi-ts to Zod 3 ecosystem (#​4942)
• 4619109 feat(locales): add Danish translations (#​4953)
• cb84a57 Point to zod-v3-to-v4 codemod in Zod 4 migration guide (#​4954)
• 28a5091 Update api.mdx (#​4955)
• 7f3cf94 Fix URL sup example (#​4959)
• 17e7f3b Add @hey-api/openapi-ts to Zod 4 ecosystem (#​4950)
• f75d852 fix: escapes decimal place in z.literal (#​4895)
• 7dd7484 v4.0.6 (#​4941)

v4.0.5

Compare Source

Commits:

• f91a73e Support pipes in discriminated unions. Closes #​4856 (#​4861)
• 45afab0 4.0.5

v4.0.4

Compare Source

Commits:

• 9335f05 Adds ZodFirstPartyTypeKind stub to fix module resolution failure inside zod-to-json-schema

v4.0.3

Compare Source

Commits:

• 5905a8d Improve check-versions script
• f3e749b Remove global File interface
• 44a936c 4.0.2
• 74006ed Fix JSR provenance
• ff4af5e 4.0.3
• ce573e8 Update test badge
• 9a7161a Fix versions

v4.0.2

Compare Source

v4.0.1: v4.0.0

Compare Source

With this release, [email protected] has been published to npm. There were no code changes between 3.25.76 and 4.0.0!

Zod 4 has been stable for the past 6 weeks, but it was published inside [email protected] on npm. this transitionary window gave the ecosystem time to incrementally support for Zod 4 (without dropping support for Zod 3). As there is now near-universal support for Zod 4 in the ecosystem, ths time feels right to finally put a bow on things 🎀

To upgrade to Zod 4:

npm upgrade zod@^4.0.0

If you’ve already migrated to Zod 4 using the subpaths, there are no changes required. however you can optionally simplify your imports (recommended)

// after upgrading to [email protected]:
import * as z from "zod"; // Zod 4 (regular)
import * as z from "zod/mini" // Zod 4 Mini

// these still work, but are no longer needed 
import * as z from "zod/v4"; 
import * as z from "zod/v4-mini":

// if you still need Zod 3
import * as z from "zod/v3"; // Zod 3

Library authors — if you've already implemented Zod 4 support according to the best practices outlined in the Library authors guide, bump your peer dependency to include zod@^4.0.0:

// package.json
{
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  }
}

There should be no other code changes necessary. No code changes were made between the latest 3.25.x release and 4.0.0. This does not require a major version bump.

v4.0.0

Compare Source