colinhacks Release Notes

Commits

4c2fa95 docs: use Zernio primary wordmark for gold sponsor logo

2aeec83 docs: prune lapsed gold sponsors and rebalance logo sizing

7391be8 docs: prune lapsed silver/bronze sponsors and add active ones

2c70332 docs: normalize bronze sponsor logos to github avatar pattern

9195250 docs: remove Mintlify from bronze sponsors (churned)

b8dffe9 docs: remove Numeric and Speakeasy (2+ missed monthly cycles)

1cab693 fix(v4): restore catch handling for absent object keys (#5937) (#5939)

c2be4f8 fix(v4): generalize optin/fallback to transform; restore preprocess on absent keys (#5941)

f3c9ec0 4.4.3

1fb56a5 docs: document release procedure in AGENTS.md

Original source

Commits

0c62df0 Clean up docs navigation and stale labels (#5901)

20cc794 chore: add security policy and refresh tooling deps

6fbe07b fix(docs): heading anchor links now include the hash so it doesnt scoll all the way up, follows navbar logic (#5791)

4bbed1b Tighten discriminated union option typing

bbac3e5 Update PR guidance for agents

cf0dc94 Merge remote-tracking branch 'origin/main' into fix-discriminated-union-key-constraint

292c894 docs: add Zernio gold sponsor

1fc9f31 docs: document codec inversion

1373c85 docs: remove AI disclosure guidance

e20d02b chore: ignore triage notes

e58ea4d docs: test Zod Mini tab code heights

905761a docs: document preprocess input type narrowing

bf64bac chore: tighten test guidance in AGENTS.md

8ec4e73 chore: update play.ts scratch

02c2baf Make z.preprocess defer optionality to inner schema (#5929)

88015df fix(docs): drop deprecated baseUrl from tsconfig

c59d447 4.4.2

Original source

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 = stringToNumber.invert();

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:

• Next.js and Turbopack tree-shaking reports: #4433, #5641, #5095, #4810
• Locale and zod/mini bundle-size reports: #5561, #5665, #4369, #4572
• Broader v4 bundle-size reports: #2596, #4637, #4798, #5206

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

Original source

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:

• All primitive types (string, number, integer, boolean, null, object, array)
• String formats (email, uri, uuid, date-time, date, time, ipv4, ipv6, and more)
• Composition (anyOf, oneOf, allOf)
• Object constraints (additionalProperties, patternProperties, propertyNames)
• Array constraints (prefixItems, items, minItems, maxItems)
• $ref for local references and circular schemas
• Custom metadata is preserved

z.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() cardinality

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

Type predicates on .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() transform

Transform 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 })
);

More ergonomic intersections

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"

New locales

Armenian (am) (#5531)
Uzbek (uz) (#5519)

import * as z from "zod";
import { uz } from "zod/locales";
z.config(uz());

Bug fixes

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({ ... })
  

• ⚠️ overwriting properties with.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
  

• ⚠️ Stricter object masking methods (#5581)
  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"
  

Additional changes

• Fixed JSON Schema generation for z.iso.time with minute precision (#5557)
• Fixed error details for tuples with extraneous elements (#5555)
• Fixed includes method params typing to accept string | $ZodCheckIncludesParams (#5556)
• Fixed numeric formats error messages to be inclusive (#5485)
• Fixed implementAsync inferred type to always be a promise (#5476)
• Tightened E.164 regex to require a non-zero leading digit and 7–15 digits total (#5524)
• Fixed Dutch (nl) error strings (#5529)
• Convert Date instances to numbers in minimum/maximum checks (#5351)
• Improved numeric keys handling in z.record() (#5585)
• Lazy initialization of ~standard schema property (#5363)
• Functions marked as @NO_SIDE_EFFECTS for better tree-shaking (#5475)
• Improved metadata tracking across child-parent relationships (#5578)
• Improved locale translation approach (#5584)
• Dropped id uniqueness enforcement at registry level (#5574)

Original source

Features

Implement Standard JSON Schema

standard-schema/standard-schema#134
Implement z.fromJSONSchema()

const jsonSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    age: { type: "number" }
  },
  required: ["name"]
};
const schema = z.fromJSONSchema(jsonSchema);

Implement z.xor()

const schema = z.xor(
  z.object({ type: "user", name: z.string() }),
  z.object({ type: "admin", role: z.string() })
);
// Exactly one of the schemas must match

Implement z.looseRecord()

const schema = z.looseRecord(z.string(), z.number());
// Allows additional properties beyond those defined

Commits

• af49c08 Update docs for JSON Schema conversion of z.undefined() (#5504)
• 767f320 Add .toJSONSchema() method (#5477)
• e17dcb6 Add z.fromJSONSchema(), z.looseRecord(), z.xor() (#5534)

Original source

Commits

• 5c2602c Update AI widget (#5318)
• d3da530 reflect the specified regex correctly in error (#5338)
• 39f8c45 faster initialization (#5352)
• e9e2790 Clean up comment
• 8e4739f Update inferred z.promise() type
• 2849df8 fix(locales): improve Dutch (nl) localization (#5367)
• b0d3c9f Run tests on windows
• 6fd61b7 feat unitest (#5358)
• a4e4bc8 Lock to node 24
• 8de8bad Fix windows build
• b2c186b Use Node LTS
• b73b1f6 Consolidate isTransforming logic
• d85f3ea Fix #5353
• 1bac0f3 Fix test.yml
• 86d4dad Fix partial record
• 5e6c0fd Fix attw on windows
• 27fc616 Extend test timeout
• 8d336c4 Remove windows runner
• 5be72e0 chore(doc): update metadata.tsx (#5331)
• cb0272a docs: add 'cd zod' step to development setup instructions (#5394)
• 24e3325 docs: replace 'Refinement' with 'Transform' in transforms section (#5397)
• 644a082 chore: add resource for validating environment variables with Zod (#5403)
• 5e1cfcf Change doc for email validation method in Zod schema (#5392)
• 88cf944 Fix: Iterate over keys in catchall object using "in" operator. (#5376)
• aa43732 Emphasise that enum validates against values, for object literal & enums (#5386)
• 3a4bd00 Improve Hebrew localization for Zod error messages (#5409)
• c10f9d1 Fix typos (#5420)
• 86f0ef9 Documentation Improvements (#5417)
• e120a48 Fix opt tuple
• f9bbb50 Improve tuple
• 0ba0f34 Optimize docs caching/ISR (#5433)
• c3ec66c Improve docs caching
• c8cce4b docs: fix typos and links (#5428)
• 84ec047 docs(ecosystem): Add react-f3 (#5429)
• 3396515 Docs: Fix typo in safeExtend description (#5445)
• 3d93a7d feat: MAC address validation in v4 and mini (#5440)
• f2f0d17 Fix dual package hazard for globalRegistry (#5452)
• 9fc493f fix: use oneOf for discriminated unions in JSON Schema (#5453)
• 603dbe8 Clean up regex, drop backreferences
• ab69b9e Update mac addr tests
• f791052 chore: upgrade vitest to v4 (#5028)
• f97e80d fix(core): prevent infinite recursion for recursive tuples (#5089) (#5094)
• 002e01a fix(record): handle non-function constructor field in isPlainObject (#5098)
• 6716517 docs(contributing): add instructions on building @zod/docs (#5114)
• 8b0603d Fix typo in ISO time documentation (#5277)
• be85ecc docs(codecs): correct stringToDate safeDecode methods (#5302)
• 50bba54 Add zodgres to ecosystem documentation (#5308)
• 377f5d1 Add zod-to-mongo-schema to ecosystem documentation (#5457)
• dea32d5 docs(ecosystem): add fn sphere and zod-compare (#5326)
• 02ea4c8 Add Claude Code GitHub Workflow (#5460)
• d44253d Add support for number literal and TypeScript's enum keys in z.record (#5334)
• f52344e Fix vitest 4
• 0f4ce73 Do not allow unsound pick/omit
• 162fe29 Add z.meta and z.describe
• 3de39ee Implement slugify
• 5bfc8f2 Fix docs
• 0e803a2 Revert "Do not allow unsound pick/omit"
• a774750 v4.1.13
• 2cdd82b 4.1.13
• 4063e80 Update check-semver script

Original 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

Original source