Skip to content

Update dependency zod to v4 (main) #205555

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update dependency zod to v4 (main) #205555

wants to merge 3 commits into from

Conversation

@elastic-renovate-prod
Copy link
Contributor

@elastic-renovate-prod elastic-renovate-prod bot commented Jan 4, 2025 •
edited
Loading

This PR contains the following updates:

Package Type Update Change Pending
zod (source) dependencies major ^3.22.3 -> ^4.1.5 4.1.9 (+3)

Release Notes

colinhacks/zod (zod)

v4.1.5

Compare Source

Commits:

v4.1.4

Compare Source

Commits:

  • 3291c61 fix(v4): toJSONSchema - wrong tuple with null output when targeting openapi-3.0 (#​5156)
  • 23f41c7 test(v4): toJSONSchema - use validateOpenAPI30Schema in all relevant scenarios (#​5163)
  • 0a09fd2 Update installation instructions
  • 4ea5fec 4.1.4

v4.1.3

Compare Source

Commits:

  • 98ff675 Drop stringToBoolean
  • a410616 Fix typo
  • 0cf4589 fix(v4): toJSONSchema - add missing oneOf inside items in tuple conversion (#​5146)
  • 8bf0c16 fix(v4): toJSONSchema tuple path handling for draft-7 with metadata IDs (#​5152)
  • 5c5fa90 fix(v4): toJSONSchema - wrong record output when targeting openapi-3.0 (#​5141)
  • 87b97cc docs(codecs): update example to use payloadSchema (#​5150)
  • 309f358 fix(v4): toJSONSchema - output numbers with exclusive range correctly when targeting openapi-3.0 (#​5139)
  • 1e71ca9 docs: fix refine fn to encode works properly (#​5148)
  • a85ec3c fix(docs): correct example to use LooseDog instead of Dog (#​5136)
  • 3e98274 4.1.3

v4.1.2

Compare Source

Commits:

v4.1.1

Compare Source

Commits:

v4.1.0

Compare Source

The first minor version since the introduction of Zod 4 back in May. This version contains a number of features that barely missed the cut for the 4.0 release. With Zod 4 stable and widely adopted, there's more time to resume feature development.

Codecs

This is the flagship feature of this release. Codecs are a new API & schema type that encapsulates a bi-directional transformation. It's a huge missing piece in Zod that's finally filled, and it unlocks some totally new ways to use Zod.

const stringToDate = z.codec(
  z.iso.datetime(),  // input schema: ISO date string
  z.date(),          // output schema: Date object
  {
    decode: (isoString) => new Date(isoString), 
    encode: (date) => date.toISOString(),
  }
);

New top-level functions are added for processing inputs in the forward direction ("decoding") and backward direction ("encoding").

stringToDate.decode("2025-08-21T20:59:45.500Z")
// => Date

stringToDate.encode(new Date())
// => "2025-08-21T20:59:45.500Z"

Note — For bundle size reasons, these new methods have not added to Zod Mini schemas. Instead, this functionality is available via equivalent top-level functions.

// equivalent at runtime
z.decode(stringToDate, "2024-01-15T10:30:00.000Z");
z.encode(stringToDate, new Date());
.parse() vs .decode()

Both .parse() and decode() process data in the "forward" direction. They behave identically at runtime.

stringToDate.parse("2025-08-21T20:59:45.500Z");
stringToDate.decode("2025-08-21T20:59:45.500Z");

There is an important difference however. While .parse() accepts any input, .decode() expects a strongly typed input. That is, it expects an input of type string, whereas .parse() accepts unknown.

stringToDate.parse(Symbol('not-a-string'));
// => fails at runtime, but no TypeScript error

stringToDate.decode(Symbol("not-a-string"));
//                     ^ ❌ Argument of type 'symbol' is not assignable to parameter of type 'Date'. ts(2345)

This is a highly requested feature unto itself:

Encoding

You can use any Zod schema with .encode(). The vast majority of Zod schemas are non-transforming (the input and output types are identical) so .decode() and .encode() behave identically. Only certain schema types change their behavior:

  • Codecs — runs from B->A and executes the encode transform during encoding
  • Pipes — these execute B->A instead of A->B
  • Defaults and prefaults — Only applied in the forward direction
  • Catch — Only applied in the forward direction

Note — To avoid increasing bundle size unnecessarily, these new methods are not available on Zod Mini schemas. For those schemas, equivalent top-level functions are provided.

The usual async and safe variants exist as well:

// decode methods
stringToDate.decode("2024-01-15T10:30:00.000Z")
await stringToDate.decodeAsync("2024-01-15T10:30:00.000Z")
stringToDate.safeDecode("2024-01-15T10:30:00.000Z")
await stringToDate.safeDecodeAsync("2024-01-15T10:30:00.000Z")

// encode methods
stringToDate.encode(new Date())
await stringToDate.encodeAsync(new Date())
stringToDate.safeEncode(new Date())
await stringToDate.safeEncodeAsync(new Date())
Example codecs

Below are some "worked examples" for some commonly-needed codecs. These examples are all tested internally for correctness. Just copy/paste them into your project as needed. There is a more comprehensive set available at zod.dev/codecs.

stringToBigInt

Converts bigint into a serializable form.

const stringToBigInt = z.codec(z.string(), z.bigint(), {
  decode: (str) => BigInt(str),
  encode: (bigint) => bigint.toString(),
});

stringToBigInt.decode("12345");  // => 12345n
stringToBigInt.encode(12345n);   // => "12345"
json

Parses/stringifies JSON data.

const jsonCodec = z.codec(z.string(), z.json(), {
  decode: (jsonString, ctx) => {
    try {
      return JSON.parse(jsonString);
    } catch (err: any) {
      ctx.issues.push({
        code: "invalid_format",
        format: "json_string",
        input: jsonString,
        message: err.message,
      });
      return z.NEVER;
    }
  },
  encode: (value) => JSON.stringify(value),
});

To further validate the data, .pipe() the result of this codec into another schema.

const Params = z.object({ name: z.string(), age: z.number() });
const JsonToParams = jsonCodec.pipe(Params);

JsonToParams.decode('{"name":"Alice","age":30}');  // => { name: "Alice", age: 30 }
JsonToParams.encode({ name: "Bob", age: 25 });     // => '{"name":"Bob","age":25}'
Further reading

For more examples and a technical breakdown of how encoding works, reads theannouncement blog post and new Codecs docs page. The docs page contains implementations for several other commonly-needed codecs:

.safeExtend()

The existing way to add additional fields to an object is to use .extend().

const A = z.object({ a: z.string() })
const B = A.extend({ b: z.string() })

Unfortunately this is a bit of a misnomer, as it allows you to overwrite existing fields. This means the result of .extend() may not literally extend the original type (in the TypeScript sense).

const A = z.object({ a: z.string() }) // { a: string }
const B = A.extend({ a: z.number() }) // { a: number }

To enforce true extends logic, Zod 4.1 introduces a new .safeExtend() method. This statically enforces that the newly added properties conform to the existing ones.

z.object({ a: z.string() }).safeExtend({ a: z.number().min(5) }); // ✅
z.object({ a: z.string() }).safeExtend({ a: z.any() }); // ✅
z.object({ a: z.string() }).safeExtend({ a: z.number() });
//                                       ^  ❌ ZodNumber is not assignable

Importantly, this new API allows you to safely extend objects containing refinements.

const AB = z.object({ a: z.string(), b: z.string() }).refine(val => val.a === val.b);
const ABC = AB.safeExtend({ c: z.string() });
// ABC includes the refinements defined on AB

Previously (in Zod 4.x) any refinements attached to the base schema were dropped in the extended result. This was too unexpected. It now throws an error. (Zod 3 did not support extension of refined objects either.)

z.hash()

A new top-level string format for validating hashes produced using various common algorithms & encodings.

const md5Schema = z.hash("md5");          
// => ZodCustomStringFormat<"md5_hex">

const sha256Base64 = z.hash("sha256", { enc: "base64" }); 
// => ZodCustomStringFormat<"sha256_base64">

The following hash algorithms and encodings are supported. Each cell provides information about the expected number of characters/padding.

Algorithm / Encoding "hex" "base64" "base64url"
"md5" 32 24 (22 + "==") 22
"sha1" 40 28 (27 + "=") 27
"sha256" 64 44 (43 + "=") 43
"sha384" 96 64 (no padding) 64
"sha512" 128 88 (86 + "==") 86

z.hex()

To validate hexadecimal strings of any length.

const hexSchema = z.hex();

hexSchema.parse("123abc");    // ✅ "123abc"
hexSchema.parse("DEADBEEF");  // ✅ "DEADBEEF" 
hexSchema.parse("xyz");       // ❌ ZodError

Additional changes

  1. z.uuid() now supports the "Max UUID" (FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF) per the RFC
  2. $ZodFunction is now a subtype of $ZodType

Commits

v4.0.17

Compare Source

Commits:

v4.0.16

Compare Source

Commits:

v4.0.15

Compare Source

Commits:

v4.0.14

Compare Source

Commits:

v4.0.13

Compare Source

Commits:

v4.0.12

Compare Source

Commits:

v4.0.11

Compare Source

Commits:

v4.0.10

Compare Source

Commits:

v4.0.9

Compare Source

Commits:

v4.0.8

Compare Source

Commits:

v4.0.7

Compare Source

Commits:

v4.0.6

Compare Source

Commits:

v4.0.5

Compare Source

Commits:

v4.0.4

Compare Source

Commits:

  • 9335f05 Adds ZodFirstPartyTypeKind stub to fix module resolution failure inside zod-to-json-schema

v4.0.3

Compare Source

Commits:

v4.0.2

Compare Source

v4.0.1: v4.0.0

Compare Source

With this release, [email protected] has been published to npm. There were no code changes between 3.25.76 and 4.0.0!

Zod 4 has been stable for the past 6 weeks, but it was published inside [email protected] on npm. this transitionary window gave the ecosystem time to incrementally support for Zod 4 (without dropping support for Zod 3). As there is now near-universal support for Zod 4 in the ecosystem, ths time feels right to finally put a bow on things 🎀

To upgrade to Zod 4:

npm upgrade zod@^4.0.0

If you’ve already migrated to Zod 4 using the subpaths, there are no changes required. however you can optionally simplify your imports (recommended)

// after upgrading to [email protected]:
import * as z from "zod"; // Zod 4 (regular)
import * as z from "zod/mini" // Zod 4 Mini

// these still work, but are no longer needed 
import * as z from "zod/v4"; 
import * as z from "zod/v4-mini":

// if you still need Zod 3
import * as z from "zod/v3"; // Zod 3

Library authors — if you've already implemented Zod 4 support according to the best practices outlined in the Library authors guide, bump your peer dependency to include zod@^4.0.0:

// package.json
{
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  }
}

There should be no other code changes necessary. No code changes were made between the latest 3.25.x release and 4.0.0. This does not require a major version bump.

v4.0.0

Compare Source

v3.25.76

Compare Source

Commits:

v3.25.75

Compare Source

Commits:

  • c5f349b Fix z.undefined() behavior in toJSONSchema

v3.25.74

Compare Source

Commits:

v3.25.73

Compare Source

Commits:

v3.25.72

Compare Source

Commits:

v3.25.71

Compare Source

Commits:

v3.25.70

Compare Source

Commits:

v3.25.69

Compare Source

Commits:

v3.25.68

Compare Source

Commits:

v3.25.67

Compare Source

Commits:

v3.25.66

Compare Source

Commits:

v3.25.65

Compare Source

Commits:

v3.25.64

Compare Source

Commits:

v3.25.63

Compare Source

Commits:

v3.25.62

Compare Source

Commits:

v3.25.61

Compare Source

Commits:

v3.25.60

Compare Source

  • no changes

v3.25.59

Compare Source

Commits:

v3.25.58

Compare Source

Commits:

v3.25.57

Compare Source

Commits:

v3.25.56

Compare Source

Commits:

v3.25.55

Compare Source

Commits:

v3.25.54

Compare Source

Commits:

  • 8ab2374 fix(util): cross realm IsPlainObject check (#​4627)
  • 2be1c6a Fix generic assignability issue. 3.25.54

v3.25.53

Compare Source

Commits:

v3.25.52

Compare Source

Commits:

v3.25.51

[Compare Source](https://redirect.github.com/colinh

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

  • If you want to rebase/retry this PR, check this box

This PR has been generated by Renovate Bot.

@elastic-renovate-prod elastic-renovate-prod bot added backport:all-open Backport to all branches that could still receive a release release_note:skip Skip the PR/issue when compiling release notes Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc. labels Jan 4, 2025
@elastic-renovate-prod elastic-renovate-prod bot requested a review from a team January 4, 2025 00:00
@elasticmachine
Copy link
Contributor

elasticmachine commented Jan 4, 2025

Pinging @elastic/security-solution (Team: SecuritySolution)

@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to ^3.24.1 (main) Update dependency zod to ^3.24.2 (main) Feb 19, 2025
@elastic-renovate-prod elastic-renovate-prod bot requested review from a team and kibanamachine as code owners April 24, 2025 07:32
@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to ^3.24.2 (main) Update dependency zod to ^3.24.3 (main) Apr 24, 2025
@jeramysoucy
Copy link
Contributor

jeramysoucy commented Apr 24, 2025

/ci

@marshallmain
Copy link
Contributor

marshallmain commented Apr 28, 2025

This appears to be blocked on errors in the ai-infra package (cc @elastic/appex-ai-infra ) because langchain is still using zod 3.23.8 and the zod type from 3.23.8 is not assignable to the updated zod type in 3.24.3.

@marshallmain marshallmain requested a review from a team April 28, 2025 18:53
@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to ^3.24.3 (main) Update dependency zod to ^3.24.4 (main) May 12, 2025
@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to ^3.24.4 (main) Update dependency zod to ^3.25.3 (main) May 26, 2025
@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to ^3.25.3 (main) Update dependency zod to ^3.25.7 (main) May 27, 2025
@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to ^3.25.7 (main) Update dependency zod to ^3.25.13 (main) May 28, 2025
@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to ^3.25.13 (main) Update dependency zod to ^3.25.16 (main) May 28, 2025
@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to ^3.25.16 (main) Update dependency zod to ^3.25.17 (main) May 28, 2025
@elastic-renovate-prod elastic-renovate-prod bot force-pushed the renovate/main-zod branch 2 times, most recently from e5b7157 to 555eebc Compare July 24, 2025 12:35
@elastic-renovate-prod elastic-renovate-prod bot force-pushed the renovate/main-zod branch 6 times, most recently from 4d0e3fe to a38cc4c Compare August 6, 2025 09:06
@elastic-renovate-prod elastic-renovate-prod bot force-pushed the renovate/main-zod branch 3 times, most recently from 5f844ae to 61a4aa6 Compare August 18, 2025 12:50
@maryam-saeidi maryam-saeidi mentioned this pull request Aug 25, 2025
Merged
1 task
@maryam-saeidi
Copy link
Member

maryam-saeidi commented Aug 25, 2025

This appears to be blocked on errors in the ai-infra package (cc @elastic/appex-ai-infra ) because langchain is still using zod 3.23.8 and the zod type from 3.23.8 is not assignable to the updated zod type in 3.24.3.

Seems like this renovate PR should help: #229504

@elastic-renovate-prod elastic-renovate-prod bot force-pushed the renovate/main-zod branch 4 times, most recently from 2006eab to 3eefe5e Compare September 4, 2025 10:13
@patrykkopycinski
Copy link
Contributor

patrykkopycinski commented Sep 13, 2025

When I was working on langchain bump I have found out that I might me worth looking to replace default zod-to-json-schema with a fork that adds support for v3 from zod@4
StefanTerdell/zod-to-json-schema#178 StefanTerdell/zod-to-json-schema#179

@elastic-renovate-prod
Copy link
Contributor Author

elastic-renovate-prod bot commented Sep 15, 2025

Edited/Blocked Notification

Renovate will not automatically rebase this PR, because it does not recognize the last commit author and assumes somebody else may have edited the PR.

You can manually request rebase by checking the rebase/retry box above.

⚠️ Warning: custom changes will be lost.

@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to v4 (main) Update dependency zod to v4 (main) - autoclosed Sep 17, 2025
@elastic-renovate-prod elastic-renovate-prod bot deleted the renovate/main-zod branch September 17, 2025 18:48
@elastic-renovate-prod elastic-renovate-prod bot changed the title Update dependency zod to v4 (main) - autoclosed Update dependency zod to v4 (main) Sep 18, 2025
@elasticmachine
Copy link
Contributor

elasticmachine commented Oct 27, 2025 •
edited
Loading

💔 Build Failed

Failed CI Steps

History

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@elena-shostak elena-shostak elena-shostak approved these changes

@kibanamachine kibanamachine Awaiting requested review from kibanamachine

Assignees

No one assigned

Labels

backport:all-open Backport to all branches that could still receive a release release_note:skip Skip the PR/issue when compiling release notes Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

7 participants

@elasticmachine @jeramysoucy @marshallmain @maryam-saeidi @patrykkopycinski @elena-shostak