Zod Release Notes

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 Report a problem

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 Report a problem

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 Report a problem