# Zod changelog

> TypeScript-first schema validation with static type inference.

- Vendor: Colin McDonnell
- Category: Frameworks & Libraries
- Official site: https://zod.dev
- Tracked by: What's New (https://whatsnew.fyi/product/zod)
- Harvested from: GitHub (colinhacks/zod)
- Entries below: 10 (newest first)

What's New is an index, not a publisher: every entry below links to the vendor's own release notes, which are the authoritative source. Entries are labelled where they are hand-curated sample data, pre-releases, or drawn from a secondary source such as a developer blog.

## Releases

### v4.4.3

- Date: 2026-05-04
- Version: v4.4.3
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.4.3
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.4.3

- **fixed** — Restore catch handling for absent object keys
- **fixed** — Generalize optin/fallback to transform and restore preprocess on absent keys

##### Commits:

- 4c2fa95ce3f3390fbc522324e406b4e9e89b88f9 docs: use Zernio primary wordmark for gold sponsor logo
- 2aeec83eb135e3a83756e973ef44845fc5a455d2 docs: prune lapsed gold sponsors and rebalance logo sizing
- 7391be88ac1ee5cd02057f5ccc012a1f5df4efd0 docs: prune lapsed silver/bronze sponsors and add active ones
- 2c703322a21b4e2b12f33f49ea8430c451a68b4f docs: normalize bronze sponsor logos to github avatar pattern
- 9195250cab0e7950efe39c3926d6c203b4b0a170 docs: remove Mintlify from bronze sponsors (churned)
- b8dffe9e62f17e6571e6249d05cc5102b54d94e4 docs: remove Numeric and Speakeasy (2+ missed monthly cycles)
- 1cab69383fcdeae2a366d5e2a2fc4d8fc765d168 fix(v4): restore catch handling for absent object keys (#5937) (#5939)
- c2be4f819064eed62c7c350a2d399b5faecd15f8 fix(v4): generalize optin/fallback to transform; restore preprocess on absent keys (#5941)
- f3c9ec03ba7a28ae72d25cc295f38674bee0f559 4.4.3
- 1fb56a5c18c27102dbc92260a4007c7732a0ccca docs: document release procedure in AGENTS.md

### v4.4.2

- Date: 2026-05-01
- Version: v4.4.2
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.4.2
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.4.2

- **fixed** — Heading anchor links now include the hash so it doesn't scroll all the way up, follows navbar logic
- **changed** — Tighten discriminated union option typing
- **changed** — Make z.preprocess defer optionality to inner schema
- **added** — Document codec inversion
- **added** — Document preprocess input type narrowing

##### Commits:

- 0c62df0ea19fd05abdf90473e9eef7eea530fab2 Clean up docs navigation and stale labels (#5901)
- 20cc794895cc8604fe0c87d83a5d1c3f89fad0ac chore: add security policy and refresh tooling deps
- 6fbe07b0177efdd1bf1c0b05160e70d7a0702337 fix(docs): heading anchor links now include the hash so it doesnt scoll all the way up, follows navbar logic (#5791)
- 4bbed1b1c73eca4ce9e59b1189ed236aa6c8b5bd Tighten discriminated union option typing
- bbac3e567e7fccfaaf7cdc97f1ce30c295e2c908 Update PR guidance for agents
- cf0dc942a32805c292fff59ade20a7ace980735a Merge remote-tracking branch 'origin/main' into fix-discriminated-union-key-constraint
- 292c894a5fd2aa42e527900b83d8d7a3009a709c docs: add Zernio gold sponsor
- 1fc9f311c28dcf80d0bb5a36b177086cbc3d8eca docs: document codec inversion
- 1373c85da9aeff704a9762d27bc58699618aefb7 docs: remove AI disclosure guidance
- e20d02b473c08e3a4e557bc610b1b5fac079b649 chore: ignore triage notes
- e58ea4d91b1dfe8194b73508203213cbc7e9c936 docs: test Zod Mini tab code heights
- 905761a5d127e8d5dd2ebb3bc88c75cb0b8149ff docs: document preprocess input type narrowing
- bf64bac850d4dee2b7dde7e64909d5d796d32043 chore: tighten test guidance in AGENTS.md
- 8ec4e73f4c4693b6361ad591be40fb41eb8a9f95 chore: update play.ts scratch
- 02c2baf7d0d615872fa4528a8020603b71211702 Make z.preprocess defer optionality to inner schema (#5929)
- 88015df8e25c44fb5385eb3ef28935119cd5edea fix(docs): drop deprecated `baseUrl` from tsconfig
- c59d4474e3b4cad1b323462186cf607178ce8267 4.4.2

### v4.4.1

- Date: 2026-04-29
- Version: v4.4.1
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.4.1
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.4.1

- **fixed** — Reject tuple holes before required defaults

##### Commits:

- 481f7be4238c83ed58183f921b2646f340a91c6a ci: gate release publishing on full test workflow
- 95ccab423aec720b2523c3a64cdc7e3204537cc7 test(v3): restore optional undefined expectations
- cede2c63739a5823d6aa5093d291e9a111da943d fix(v4): reject tuple holes before required defaults (#5900)
- edd0bf0f5ada4a8dc581c259407d7bbad0a71ea7 release: 4.4.1
- 180d83d1dbe6a59260710cc8637a3dea2281ee56 docs: remove Jazz featured sponsor

### v4.4.0

- Date: 2026-04-29
- Version: v4.4.0
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.4.0
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.4.0

- **fixed** — Tuple parsing now correctly materializes default values in the output, optional tails, and handles explicit undefined values
- **changed** — Object properties with z.undefined() schema are now treated as required, with the key needing to be present but value allowed to be undefined
- **fixed** — The merge() method now throws when the receiver has refinements instead of silently producing ambiguous refinement behavior
- **fixed** — JSON Schema $defs entries no longer include redundant id fields to ensure correct reference resolution
- **fixed** — Base64 validation now rejects whitespace instead of allowing atob()-style whitespace stripping
- **changed** — CUID validation has been tightened and CUID v1 is now deprecated
- **changed** — HTTP URL validation now rejects malformed HTTP(S) URLs with a missing slash after the protocol
- **fixed** — Nested union paths are now preserved correctly in z.treeifyError() and z.formatError() output
- **fixed** — Invalid discriminated union errors now include discriminator options and improved messages
- **fixed** — JSON Schema Draft-04/OpenAPI 3.0 min/max intersections are now handled correctly
- **fixed** — Recursive lazy schemas with describe() now work correctly in JSON Schema conversion
- **fixed** — Falsy prefault values are now emitted as defaults in JSON Schema output
- **fixed** — CUID pattern output in JSON Schema has been tightened

##### 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](https://github.com/colinhacks/zod/pull/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.

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

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

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

But explicit `undefined` values supplied by the caller are preserved.

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

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

```ts
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](https://github.com/colinhacks/zod/pull/5661), with follow-up coverage in [`57d80a82`](https://github.com/colinhacks/zod/commit/57d80a82bde8877f3eb79e5dad9786096c37490f). A property whose schema is `z.undefined()` is now treated as required. The key must be present, but its value may be `undefined`.

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

```ts
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](https://github.com/colinhacks/zod/pull/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.

```ts
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](https://github.com/colinhacks/zod/pull/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](https://github.co

_[Truncated at 4000 characters — full notes: https://github.com/colinhacks/zod/releases/tag/v4.4.0]_

### v4.3.6

- Date: 2026-01-22
- Version: v4.3.6
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.3.6
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.3.6

##### Commits:

- 9977fb0868432461de265a773319e80a90ba3e37 Add brand.dev to sponsors
- f4b7bae3468f6188b8f004e007d722148fc91d77 Update pullfrog.yml (#5634)
- 251d7163a0ac7740fee741428d913e3c55702ace Clean up workflow_call
- edd4132466da0f5065a8e051b599d01fdd1081d8 fix: add missing User-agent to robots.txt and allow all (#5646)
- 85db85e9091d0706910d60c7eb2e9c181edd87bd fix: typo in codec.test.ts file (#5628)
- cbf77bb12bdfda2e054818e79001f5cb3798ce76 Avoid non null assertion (#5638)
- dfbbf1c1ae0c224b8131d80ddf0a264262144086 Avoid re-exported star modules (#5656)
- 762e911e5773f949452fd6dd4e360f2362110e8e Generalize numeric key handling
- ca3c8629c0c2715571f70b44c2433cad3db7fe4e v4.3.6

### v4.3.5

- Date: 2026-01-04
- Version: v4.3.5
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.3.5
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.3.5

##### Commits:

- 21afffdb42ccab554036312e33fed0ea3cb8f982 [Docs] Update migration guide docs for deprecation of message (#5595)
- e36743e513aadb307b29949a80d6eb0dcc8fc278 Improve mini treeshaking
- 0cdc0b8597999fd9ca99767b912c1e82c1ff2d6c 4.3.5

### v4.3.4

- Date: 2025-12-31
- Version: v4.3.4
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.3.4
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.3.4

##### Commits:

- 1a8bea3b474eada6f219c163d0d3ad09fadabe72 Add integration tests
- e01cd02b2f23d7e9078d3813830b146f8a2258b4 Support patternProperties for looserecord (#5592)
- 089e5fbb0f58ce96d2c4fb34cd91724c78df4af5 Improve looseRecord docs
- decef9c418d9a598c3f1bada06891ba5d922c5cd Fix lint
- 9443aab00d44d5d5f4a7eada65fc0fc851781042 Drop iso time in fromJSONSchema
- 66bda7491a1b9eab83bdeec0c12f4efc7290bd48 Remove .refine() from ZodMiniType
- b4ab94ca608cd5b581bfc12b20dd8d95b35b3009 4.3.4

### v4.3.3

- Date: 2025-12-31
- Version: v4.3.3
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.3.3
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.3.3

##### Commits:

- f3b2151959d215d405f54dff3c7ab3bf1fd887ca v4.3.3

### v4.3.2

- Date: 2025-12-31
- Version: v4.3.2
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.3.2
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.3.2

##### Commits:

- bf96635d243118de6e4f260077aa137453790bf6 Loosen strictObjectinside intersection (#5587)
- f71dc0182ab0f0f9a6be6295b07faca269e10179 Remove Juno (#5590)
- 0f41e5a12a43e6913c9dcb501b2b5136ea86500d 4.3.2

### v4.3.1

- Date: 2025-12-31
- Version: v4.3.1
- Original notes: https://github.com/colinhacks/zod/releases/tag/v4.3.1
- Permalink: https://whatsnew.fyi/product/zod/releases/v4.3.1

##### Commits:

- 0fe88407a4149c907929b757dc6618d8afe998fc allow non-overwriting extends with refinements. 4.3.1