Zod Release Notes

This is Zod's biggest release since 4.0. It addresses several of Zod's longest-standing feature requests.

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 …

Features

Implement Standard JSON Schema

https://github.com/standard-schema/standard-schema/pull/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:

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

Commits:

• 5c2602ceb8be8941c64bbe5ac7d92cc174ae6f7e Update AI widget (#5318)
• d3da530deb713c853e79405adddf770e156d50ac reflect the specified regex correctly in error (#5338)
• 39f8c45b8a29de2330b485862b83cb35849f4238 faster initialization (#5352)
• e9e27905cc0f37cb079ea473af8359d5e17a57a1 Clean up comment
• 8e4739fadbd7de710eb67d34ba7e06a1029a68ab Update inferred z.promise() type
• 2849df8907b011ab056d67ae8e3d27577ac4ed3e fix(locales): improve Dutch (nl) localization (#5367)
• b0d3c9f628b60d358b66acf8f0ef7937fc9e8950 Run tests on windows
• 6fd61b71b85e4fef4c168a46c3ebcc574f26255f feat unitest (#5358)
• a4e4bc80e204577c698cf1369dd63c2b986d35f3 Lock to node 24
• 8de8bad0fa84194b81efd32474462d7a236a1ee4 Fix windows build
• b2c186bbae3a74a12acd385c1ced3ed978235cf8 Use Node LTS
• b73b1f61c798efdf497852872b4c19cd4111c1f3 Consolidate isTransforming logic
• d85f3ea4da53a1b232017dd4e4a2874eca4d8d76 Fix #5353
• 1bac0f37b529eb9a0d833a01200f5a898e8e6220 Fix test.yml
• 86d4dad5bc27b4b35df533c9170a552ad8c6c3bc Fix partial record
• 5e6c0fd7471636feffe5763c9b7637879da459fe Fix attw on windows
• 27fc616b8edb93cc27a4d25b37479d6e418bbccf Extend test timeout
• 8d336c4d15e1917d78b67b890f7182f26633b56f Remove windows runner
• 5be72e0ef4dceb1387febb7981079ecdeb5e2817 chore(doc): update metadata.tsx (#5331)
• cb0272a0ad9962df95832a78587f54afec685351 docs: add 'cd zod' step to development setup instructions (#5394) …

Commits:

• 0b109c37c6b0b10e3901b56bcccb72e29a0b846f docs(ecosystem): add bupkis to the ecosystem section (#5237)
• d22ec0d26fab27151b0f1d1f98bffeaf8b011f57 docs(ecosystem): add upfetch (#5238)
• c56a4f6fab42c542b191228af61974b2328dc52f docs(ecosystem): add eslint-plugin-zod-x (#5261)
• a0abcc02900a4293dd4f30cd81580efcdd5230bb docs(metadata.mdx): fix a mistake in an example output (#5248)
• 62bf4e439e287e55c843245b49f8d34b1ad024ee fix(ZodError): prevent flatten() from crashing on 'toString' key (#5266)
• 02a584010ac92ac8a351632ae5aea3983a6f17d8 refac(errors): Unify code structure and improve types (#5278)
• 4b1922ad714e12dafaa83a40ec03275a39ac980c docs(content/v4/index): fix zod version (#5289)
• 3fcb20ff348e49aec70f45e0dca3de8a61450e77 Add frrm to ecosystem (#5292)
• fda4c7c2afbd7649261be1e7954f8c4d4de24a07 Make docs work without token
• af447384379faef28aa857fb53ef1da702c6d408 Fix lint
• 77c3c9f069a4cf168c0cbc58432803de887a6b1b Export bg.ts
• 3b946107b6c94b2ac8ff9fb451160c34dc4dd794 v4.1.12