Skip to content
verdict:

Zod 4.3.0

notable

Release notes

note: no summary for this older release

We summarize recent releases. The original release notes for this version are below.

release-notesgithub.com/colinhacks/zod · 303 lines
  1. This is Zod's biggest release since 4.0. It addresses several of Zod's longest-standing feature requests.
  3. ## `z.fromJSONSchema()`
  5. Convert JSON Schema to Zod ([#5534](https://github.com/colinhacks/zod/pull/5534), [#5586](https://github.com/colinhacks/zod/pull/5586))
  7. 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.
  9. ```typescript
  10. import * as z from "zod";
  12. const schema = z.fromJSONSchema({
  13. type: "object",
  14. properties: {
  15. name: { type: "string", minLength: 1 },
  16. age: { type: "integer", minimum: 0 },
  17. },
  18. required: ["name"],
  19. });
  21. schema.parse({ name: "Alice", age: 30 }); // ✅
  22. ```
  24. 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.
  26. Features supported:
  27. - All primitive types (`string`, `number`, `integer`, `boolean`, `null`, `object`, `array`)
  28. - String formats (`email`, `uri`, `uuid`, `date-time`, `date`, `time`, `ipv4`, `ipv6`, and more)
  29. - Composition (`anyOf`, `oneOf`, `allOf`)
  30. - Object constraints (`additionalProperties`, `patternProperties`, `propertyNames`)
  31. - Array constraints (`prefixItems`, `items`, `minItems`, `maxItems`)
  32. - `$ref` for local references and circular schemas
  33. - Custom metadata is preserved
  35. ## `z.xor()` — exclusive union ([#5534](https://github.com/colinhacks/zod/pull/5534))
  37. 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.
  39. ```typescript
  40. const schema = z.xor([z.string(), z.number()]);
  42. schema.parse("hello"); // ✅
  43. schema.parse(42); // ✅
  44. schema.parse(true); // ❌ zero matches
  45. ```
  47. When converted to JSON Schema, `z.xor()` produces `oneOf` instead of `anyOf`.
  49. ## `z.looseRecord()` — partial record validation ([#5534](https://github.com/colinhacks/zod/pull/5534))
  51. 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.
  53. ```typescript
  54. const schema = z.looseRecord(z.string().regex(/^S_/), z.string());
  56. schema.parse({ S_name: "John", other: 123 });
  57. // ✅ { S_name: "John", other: 123 }
  58. // only S_name is validated, "other" passes through
  59. ```
  61. ## `.exactOptional()` — strict optional properties ([#5589](https://github.com/colinhacks/zod/pull/5589))
  63. A new wrapper that makes a property *key-optional* (can be omitted) but does **not** accept `undefined` as an explicit value.
  65. ```typescript
  66. const schema = z.object({
  67. a: z.string().optional(), // accepts `undefined`
  68. b: z.string().exactOptional(), // does not accept `undefined`
  69. });
  71. schema.parse({}); // ✅
  72. schema.parse({ a: undefined }); // ✅
  73. schema.parse({ b: undefined }); // ❌
  74. ```
  76. This makes it possible to accurately represent the full spectrum of optionality expressible using [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig/exactOptionalPropertyTypes.html).
  78. ## `.apply()`
  80. A utility method for applying arbitrary transformations to a schema, enabling cleaner schema composition. ([#5463](https://github.com/colinhacks/zod/pull/5463))
  82. ```typescript
  83. const setCommonChecks = <T extends z.ZodNumber>(schema: T) => {
  84. return schema.min(0).max(100);
  85. };
  87. const schema = z.number().apply(setCommonChecks).nullable();
  88. ```
  90. ## `.brand()` cardinality
  92. The `.brand()` method now accepts a second argument to control whether the brand applies to input, output, or both. Closes [#4764](https://github.com/colinhacks/zod/issues/4764), [#4836](https://github.com/colinhacks/zod/issues/4836).
  94. ```typescript
  95. // output only (default)
  96. z.string().brand<"UserId">(); // output is branded (default)
  97. z.string().brand<"UserId", "out">(); // output is branded
  98. z.string().brand<"UserId", "in">(); // input is branded
  99. z.string().brand<"UserId", "inout">(); // both are branded
  100. ```
  102. ## Type predicates on `.refine()` ([#5575](https://github.com/colinhacks/zod/pull/5575))
  104. The `.refine()` method now supports type predicates to narrow the output type:
  106. ```typescript
  107. const schema = z.string().refine((s): s is "a" => s === "a");
  109. type Input = z.input<typeof schema>; // string
  110. type Output = z.output<typeof schema>; // "a"
  111. ```
  113. ## `ZodMap` methods: `min`, `max`, `nonempty`, `size` ([#5316](https://github.com/colinhacks/zod/pull/5316))
  115. `ZodMap` now has parity with `ZodSet` and `ZodArray`:
  117. ```typescript
  118. const schema = z.map(z.string(), z.number())
  119. .min(1)
  120. .max(10)
  121. .nonempty();
  123. schema.size; // access the size constraint
  124. ```
  126. ## `.with()` alias for `.check()` ([359c0db](https://github.com/colinhacks/zod/commit/359c0db6))
  128. 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.
  130. ```typescript
  131. z.string().with(
  132. z.minLength(5),
  133. z.toLowerCase()
  134. );
  136. // equivalent to:
  137. z.string().check(
  138. z.minLength(5),
  139. z.trim(),
  140. z.toLowerCase()
  141. );
  142. ```
  144. ## `z.slugify()` transform
  146. Transform strings into URL-friendly slugs. Works great with `.with()`:
  148. ```typescript
  149. // Zod
  150. z.string().slugify().parse("Hello World"); // "hello-world"
  153. // Zod Mini
  154. // using .with() for explicit check composition
  155. z.string().with(z.slugify()).parse("Hello World"); // "hello-world"
  156. ```
  158. ## `z.meta()` and `z.describe()` in Zod Mini ([947b4eb](https://github.com/colinhacks/zod/commit/947b4eb2))
  160. Zod Mini now exports `z.meta()` and `z.describe()` as top-level functions for adding metadata to schemas:
  162. ```typescript
  163. import * as z from "zod/mini";
  165. // add description
  166. const schema = z.string().with(
  167. z.describe("A user's name"),
  168. );
  170. // add arbitrary metadata
  171. const schema2 = z.number().with(
  172. z.meta({ deprecated: true })
  173. );
  174. ```
  176. ## More ergonomic intersections https://github.com/colinhacks/zod/pull/5587
  178. 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.
  180. This means keys that are recognized by at least one side of the intersection will now pass validation:
  182. ```ts
  183. const A = z.strictObject({ a: z.string() });
  184. const B = z.object({ b: z.string() });
  186. const C = z.intersection(A, B);
  188. // Keys recognized by either side now work
  189. C.parse({ a: "foo", b: "bar" }); // ✅ { a: "foo", b: "bar" }
  191. // Extra keys are stripped (follows strip behavior from B)
  192. C.parse({ a: "foo", b: "bar", c: "extra" }); // ✅ { a: "foo", b: "bar" }
  193. ```
  195. When both sides are strict, only keys unrecognized by *both* sides will error:
  197. ```ts
  198. const A = z.strictObject({ a: z.string() });
  199. const B = z.strictObject({ b: z.string() });
  201. const C = z.intersection(A, B);
  203. // Keys recognized by either side work
  204. C.parse({ a: "foo", b: "bar" }); // ✅
  206. // Keys unrecognized by BOTH sides error
  207. C.parse({ a: "foo", b: "bar", c: "extra" });
  208. // ❌ ZodError: Unrecognized key: "c"
  209. ```
  211. ## New locales
  213. - Armenian (`am`) ([#5531](https://github.com/colinhacks/zod/pull/5531))
  214. - Uzbek (`uz`) ([#5519](https://github.com/colinhacks/zod/pull/5519))
  216. ```ts
  217. import * as z from "zod";
  218. import { uz } from "zod/locales";
  220. z.config(uz());
  221. ```
  223. <br/><br/><br/>
  225. ## Bug fixes
  227. 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.
  229. ### ⚠️ `.pick()` and `.omit()` disallowed on object schemas containing refinements ([#5317](https://github.com/colinhacks/zod/pull/5317))
  231. Using `.pick()` or `.omit()` on object schemas with refinements now throws an error. Previously, this would silently drop the refinements, leading to unexpected behavior.
  233. ```typescript
  234. const schema = z.object({
  235. password: z.string(),
  236. confirmPassword: z.string(),
  237. }).refine(data => data.password === data.confirmPassword);
  239. schema.pick({ password: true });
  240. // 4.2: refinement silently dropped ⚠️
  241. // 4.3: throws error ❌
  242. ```
  244. **Migration**: The easiest way to migrate is to create a new schema using the `shape` of the old one.
  246. ```ts
  247. const newSchema = z.object(schema.shape).pick({ ... })
  248. ```
  250. ### ⚠️ overwriting properties with`.extend()` disallowed on object schemas with refinements ([#5317](https://github.com/colinhacks/zod/pull/5317))
  252. Similarly, `.extend()` will throws on schemas with refinements *if* you are overwriting existing properties.
  254. ```typescript
  255. const schema = z.object({
  256. a: z.string()
  257. }).refine(/* ... */);
  259. schema.extend({ a: z.number() }); // 4.3: throws error ❌
  260. ```
  262. Instead you can use `.safeExtend()`, which statically ensures that you aren't changing the type signature of any pre-existing properties.
  264. ```typescript
  265. const schema = z.object({
  266. a: z.string(),
  267. }).refine(/* ... */);
  269. schema.safeExtend({
  270. a: z.string().min(5).max(10)
  271. }); // ✅ allows overwrite, preserves refinement
  272. ```
  274. ### ⚠️ Stricter object masking methods ([#5581](https://github.com/colinhacks/zod/pull/5581))
  276. Object masking methods (`.pick()`, `.omit()`) now validate that the keys provided actually exist in the schema:
  278. ```typescript
  279. const schema = z.object({ a: z.string() });
  281. // 4.3: throws error for unrecognized keys
  282. schema.pick({ nonexistent: true });
  283. // error: unrecognized key: "nonexistent"
  284. ```
  286. <br/><br/><br/>
  288. ## Additional changes
  290. - Fixed JSON Schema generation for `z.iso.time` with minute precision ([#5557](https://github.com/colinhacks/zod/pull/5557))
  291. - Fixed error details for tuples with extraneous elements ([#5555](https://github.com/colinhacks/zod/pull/5555))
  292. - Fixed `includes` method params typing to accept `string | $ZodCheckIncludesParams` ([#5556](https://github.com/colinhacks/zod/pull/5556))
  293. - Fixed numeric formats error messages to be inclusive ([#5485](https://github.com/colinhacks/zod/pull/5485))
  294. - Fixed `implementAsync` inferred type to always be a promise ([#5476](https://github.com/colinhacks/zod/pull/5476))
  295. - Tightened E.164 regex to require a non-zero leading digit and 7–15 digits total ([#5524](https://github.com/colinhacks/zod/pull/5524))
  296. - Fixed Dutch (nl) error strings ([#5529](https://github.com/colinhacks/zod/pull/5529))
  297. - Convert `Date` instances to numbers in `minimum`/`maximum` checks ([#5351](https://github.com/colinhacks/zod/pull/5351))
  298. - Improved numeric keys handling in `z.record()` ([#5585](https://github.com/colinhacks/zod/pull/5585))
  299. - Lazy initialization of `~standard` schema property ([#5363](https://github.com/colinhacks/zod/pull/5363))
  300. - Functions marked as `@__NO_SIDE_EFFECTS__` for better tree-shaking ([#5475](https://github.com/colinhacks/zod/pull/5475))
  301. - Improved metadata tracking across child-parent relationships ([#5578](https://github.com/colinhacks/zod/pull/5578))
  302. - Improved locale translation approach ([#5584](https://github.com/colinhacks/zod/pull/5584))
  303. - Dropped id uniqueness enforcement at registry level ([#5574](https://github.com/colinhacks/zod/pull/5574))

view on githubimported 2026-09-28 via npm