TL;DR

Zod v4.4.0 introduces stricter parsing for tuples and object properties, potentially breaking code relying on previously accepted invalid inputs, but improves data integrity and predictability.

Breaking

• Tuple Defaults: Tuple parsing now accurately reflects defaults, optional tails, and undefined values, potentially changing parsed output.
• Required z.undefined(): Properties with z.undefined() are now treated as required; use .optional() if the key itself may be absent.
• .merge() with Refinements: .merge() now throws when the receiver has refinements; use .extend() or .safeExtend() instead.
• JSON Schema $defs ID: Redundant id fields are removed from JSON Schema $defs entries, potentially affecting consumers reading those internal fields.

New

• Improved Tuple Handling: More accurate handling of defaults and optional elements within tuples.
• Safer Object Composition: Encourages use of .extend() and .safeExtend() over .merge() for clearer object composition.

Fixes Worth Knowing

• Fixed an issue where absent object keys were not correctly handled during parsing.
• Heading anchor links in documentation now function correctly.
• Improved discriminated union typing for better type safety.
• Corrected tuple length errors for more consistent behavior.

TL;DR

Zod now supports defining custom string formats with z.stringFormat(), enabling more precise string validation beyond built-in types like email or URL.

New

• Custom String Formats: z.stringFormat() allows developers to define and validate strings against regular expressions directly within their Zod schemas.
• Esperanto Locale: Added support for the Esperanto (eo) locale for improved internationalization.
• Ecosystem Integrations: Several new integrations were added to the ecosystem listing, including svelte-jsonschema-form and zod-xlsx.

Fixes Worth Knowing

• Fixed an issue with z.undefined() not correctly serializing to JSON Schema.
• Corrected optionality handling within schemas.
• Improved error messages for length checks, now including exact for precise validation.
• Fixed a bug where defaults were being overwritten.

Before You Upgrade

• If you rely on the internal structure of Zod, be aware that source files have been moved to a /src directory and then reverted, which may affect some tooling.

TL;DR

Zod has been restructured into three packages – zod, @zod/mini (tree-shakable Zod), and @zod/core (shared logic) – and is now in beta, requiring updates to your import statements.

Breaking

• Import paths have changed (package restructuring).
• Zod 4 is not yet fully stable (beta release).

New

• @zod/mini provides a smaller bundle size (optimized for web).

Before You Upgrade

• Update your imports to use the new package structure: zod, @zod/mini, and @zod/core.
• Install the beta versions using npm upgrade zod@next and npm install @zod/mini@next.

TL;DR

Zod now validates date, time, and duration strings using the ISO 8601 standard, expanding its data validation capabilities.

Breaking

• .pick() and .omit() now strictly enforce known keys, potentially causing compiler errors if invalid keys are used.
• The default generic type in ZodType changed to unknown, which may affect some recursive schema definitions or generic functions.
• Changes to ZodFirstPartySchemaTypes may impact codegen libraries.

New

• Date/Time/Duration Validation: Zod can now validate ISO 8601 date, time, and duration strings using z.string().date(), z.string().time(), and z.string().duration().
• Improved Datetime Handling: z.string().datetime() now supports unqualified (timezone-less) datetimes with local: true and validates day-of-month for accuracy.
• Base64 Validation: Added z.string().base64() for validating base64 encoded strings.

Fixes Worth Knowing

• Fixed an issue where z.record().parse could filter out undefined values.
• Improved performance of enum comparisons.
• Corrected email validation to disallow commas.
• Fixed a bug in cuid2 validation.

Before You Upgrade

• Review your use of .pick() and .omit() to ensure only valid keys are used.
• If you are using recursive schemas or generic functions with ZodType, verify compatibility with the new default generic type of unknown.

TL;DR

Zod v3 introduces a new parser, significantly improving performance and enabling more robust schema validation.

Breaking

• z.nativeEnum is removed (enum handling is now built-in).
• z.discriminatedUnion now requires a discriminator key (improves type safety).

New

• Improved error messages provide more specific guidance for fixing validation issues.
• Schemas can now be created directly from TypeScript classes (enhanced interoperability).

Fixes Worth Knowing

• Fixed an issue where optional fields were incorrectly validated when using .superRefine.
• Corrected handling of date parsing with different timezones (improves data accuracy).

Before You Upgrade

• Update your enum definitions to use the new built-in enum support instead of z.nativeEnum.
• Ensure your discriminated unions explicitly define a discriminator key.

Package: Zod Release:

--- v3.0.0-rc.5 (2024-05-02) ---

What’s Changed

• feat(parsers): add support for Date parsing with timezone support by @catalinr (c67618d)
• fix(parsers): fix date parsing with timezone by @catalinr (68f6113)
• fix: fix issue with optional fields and superRefine by @schickling (9449c8f)
• fix: fix discriminated union type by @schickling (b9d16f3)
• docs: update discriminated union docs by @schickling (640681a)

Package: Zod Release:

--- v3.0.0-rc.1 (2024-04-15) ---

What’s Changed

• feat: add support for classes by @schickling (a4a2062)
• feat: improve error formatting by @schickling (6194917)
• feat: remove native enum by @schickling (f7f7160)
• feat: discriminated union requires discriminator key by @schickling (420a94e)
• fix: fix discriminated union type by @schickling (b9d16

TL;DR

Zod now offers more flexible data validation with the addition of safeParse, enabling functional validation similar to io-ts (a type checking library).

New

• safeParse allows for functional data validation, providing more robust error handling.
• regex method added to string schemas for pattern matching.
• primitives() and nonprimitives() methods simplify object schema manipulation (filtering fields).
• z.nativeEnum() creates schemas directly from TypeScript enums (predefined sets of values).

Fixes Worth Knowing

Several minor validation issues addressed (related to issues #120, #121, #125, #127, #128).