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.
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, , , , , , , , and more)
⚠️ .pick() and .omit() disallowed on object schemas containing refinements (#5317)
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.
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
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
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"
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.
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"
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.
