Zod 4

Many thanks for your work! Definitely looking forward to the upgrade - especially the performance-boosts with regards to tsc will be very welcome in our relatively large code-base, and the changes to discriminated unions will probably help us big time in a very specific scenario where so far they fell short.

That being said, I'm fully understanding of the reasons for the somewhat odd versioning given your special situation, but still, I'd wish there would be a 4.0.0-package for folks like us who simply don't need to worry or bother about zod-version-clashes in transitive dependencies bacause those don't exist (or at least I think so; npm ls zod only returns our own dependency of zod). If I understood correctly, we'll need to adapt the import to "zod/v4", which will be an incredibly noisy change and will probably cause quite a few headaches when IDEs auto-import from 'zod' and such, which we then need to catch with linting-rules.

But that's probably a small gripe for a what sounds overall like a very promising upgrade - many thanks for your work once again!

Sorry if it's mentioned in the article but I'm on mobile.

Is fixing .optional() in TS[0] part of the 9/10 top-issues fixed? This has been my biggest pain point with Zod... but still Zod is so good I still choose to just deal with it :) Thanks for an amazing part of the ecosystem.

[0] https://github.com/colinhacks/zod/issues/635

First thank you for the hard work, many of my local hacks will go away with the new features!

As a convenience and mostly avoid typos in form names I use my own version of https://github.com/raflymln/zod-key-parser. I've been surprised something like this hasn't been implemented directly in the library.

Curious if you think this is out of scope for Zod or just something you haven't gotten around to implement?

(Here are discussions around it: https://github.com/colinhacks/zod/discussions/2134)

I had so much difficulty with recursive types mixed with discriminated union (think xml in json for example) hopefully it'll be better now

A perfectly valid evolution strategy is to add new APIs while keeping the old (which you may or may not choose to deprecate). That is, add the new APIs to 3.x (but probably call them something other than v4.

Now, that's effectively what 3.25 is. But there are some problematic extras... the semantics of the semantic versioning is muddled. That means confusion, which means some people will spin their wheels after not initially grokking the situation correctly. Also, there seems to be an implication there could be a strong deprecation of v3 APIs coming. That is, you have to wonder how long the window for incremental migration will remain open.

To be frank, I wouldn't touch zod on any project I hoped will be around for a while. Predicting the future is an uncertain business, but we can look at the past. In a few years, I think it's reasonable to guess zod v4 will be getting the same treatment zod v3 is getting now.

Not that I think you ought to do anything different. I probably wouldn't want to maintain some old API I came up with years ago indefinitely either (not without a decent support contract, that is).

The path of least short term pain is often the best path.

Everyone old in Python ecosystem remembers the Python 2/3 migration madness.

Big thank you for the work on Zod - it's a fantastic library and it's been incredibly valuable for data validation/parsing in Node environments for me over the last two years.

Am I to understand the earliest version of Zod 4 is 3.25.0?

Does this not sound insane?

---

I've been using the alpha versions of Zod for months, I just want to edit package.json and upgrade. But now I need to shotgun across git history instead.

Colin, I appreciate your project immensely. As a point of feedback, you made this ^ much harder than you had to. (Perhaps publish a 4.x along with the 3.x stuff?)

Author here. I wrote a fairly detailed writeup here[0] for those who are interested in the reasons for this approach.

Ultimately you're right that npm doesn't work well to manage the situation Zod finds itself in. But Zod is subject to a bunch of constraints that virtually no other libraries are subject to. There are dozens or hundreds of libraries that directly import interfaces/classes from "zod" and use them in their own public-facing API.

Since these libraries are directly coupled to Zod, they would need to publish a new major version whenever Zod does. That's ultimately reasonable in isolation, but in Zod's case it would trigger a "version avalanche" would just be painful for everyone involved. Selfishly, I suspect it would result in a huge swath of the ecosystem pinning on v3 forever.

The approach I ended up using is analogous to what Golang does. In essence a given package never publishes new breaking versions: they just add a new subpath when a new breaking release is made. In the TypeScript ecosystem, this means libraries can configure a single peer dependency on zod@^3.25.0 and support both versions simultaneously by importing what they need from "zod/v3" and "zod/v4". It provides a nice opt-in incremental upgrade path for end-users of Zod too.

[0] https://github.com/colinhacks/zod/issues/4371

> Peer dependencies are so broken that they had to make v4 pretend it's v3

I'm not sure this is the right conclusion here. I think zod v4 is being included within v3 so consumers can migrate over incrementally. I.e refactor all usages, one by one to `import ... from 'zod/v4'`, and once that's done, upgrade to v4 entirely.

I feel like people will upvote anything negative. This is not much a limitation of npm, there's nothing intrinsically wrong with npm that lead to this decision, this is more a pragmatic way of allowing progressive change of a library that introduced a lot of braking changes.

I might be blindsided by using npm exclusively for years by this point, but what would be a better way to support iteratively migrating from v3 to v4 without having to do it all in one large batch?

We've been using zod 4 beta already with great improvements but due to our huge codebase not being able to handle the required moduleResolution settings, we cannot upgrade...

They could at least also publish it as a major version without the legacy layer

EDIT: I've just seen the reason described here: https://github.com/colinhacks/zod/issues/4371 TLDR: He doesn't want to trigger a "version bump avalanche" across the ecosystem. (Which I believe, wouldn't happen as they could still backport fixes and support the v3 for a time, as they do it right now)

apart from the other things people raised, as leerob also points out it hints to an llm that the api may be different https://x.com/leerob/status/1924504939818008791

I feel like both Node.js and NPM were initially vibe coded before LLMs existed. Just a quick hack, kind of, that got hugely popular somewhat by accident.

Edit: Thinking about it, that's the origin story of JavaScript as well, so rather fitting.

I think you would use discrimated unions.

const MyResult = z.discriminatedUnion("status", [ z.object({ status: z.literal("success"), data: z.string() }), z.object({ status: z.literal("failed"), error: z.string() }), ]);

You can define passthrough behavior if there are a bunch of special attributes for a moderator but you don't want to list/check them all.

With different methods that have different schema- If they share part of the same schema with alterations, you can define an object for the shared part and create objects that contain the shared object schema with additional fields.

If you have a lot of different possibilities, it will be messy, but it sounds like it already is for you, so validators could still at least validate the messines.

In an ideal world you'd have one source of truth for what the shape of a User could be (which may well be a discriminated union of User and AnonymousUser or similar).

Without fullstack TS this could look something like: (for a Python backend) Pydantic models+union for the various shapes of `User`, and then OpenAPI/GraphQL schema generation+codegen for the TS client.

Your server should export the types. Don't write types by hand in your client, that makes no sense. The server knows what data it is sending and should provide that information as metadata to the client. Practically this can mean that a Python backend uses Pydantic schemas which can be used to automatically generate an OpenAPI specification that your client can use to generate types.

It's hard to unpack without knowing more about the use case, but adding discriminant properties (e.g. "user_type") to all the types in the union can make it easier to handle the general and specific case.

E.g.

if (user.user_type === 'authenticated') {

  // do something with user.name because the type system knows we have that now

}

This doesn't help in your case, but this is what GraphQL was invented for.

TS libraries for GQL queries can dynamically infer the response shape from the shape of the selected fields.

Such that the query

    query {
        user {
            username
            posts {
                text
            }
        }
    }

    type Response = {
        user: {
            username: string
            posts: Array<{
                text: string
            }>
        }
    }

Either Unions, or optional fields

I was looking at all their speed metrics, and can you explain to me where the speed makes a difference?

We only use zod to validate forms, so I keep thinking "how does this matter?" Are people maybe using it to validate high throughput API input messages or something like that, where performance may matter more?

Interesting, that one didn't even appear in my research. I was specifically looking for typescript ergonomics too. Probably still not going to switch away from Zod, though.

ArkType is a nightmare to use, zod is nice to use

Why ArkType over TypeBox?

I am 100% in agreement here. I operate a couple large Next.js apps and in the last year we've had to deal with Next.js 14 -> 15 which introduced a ton of breaking cache changes, Next.js pages -> app router, React 18 -> 19, Eslint 8 -> 9, and Tailwind 3 -> 4.

It's honestly been a nightmare, and I wish I had just built in Django instead. The Tailwind 3 -> 4 migration was probably among the most painful, which I was not expecting.

that's why they're taking the dual-availability approach, with a separate 'mini' edition. it's easy to perform a progressive migration without messing with the package manager.

consumers uninterested in the 'mini' edition don't have to bother with that part.

but, the benefits of the 'mini' edition are so drastic for tree-shaking that it was driving development of alternatives - zod had to either do it (and benefit), or deprecate.

> For projects that rely heavily on Zod, it feels like a daunting task ahead—one that will demand a lot of developer attention and time to navigate.

Or just use an LLM.

TypeScript's insistence on being a static checking/compile time only system is such a sad wound to the whole ecosystem. I don't want TypeScript to be a runtime checker, but I want it to export useful usable type data for classes, functions, objects. TypeScript feels like the best source of truth we have, but instead so many of the attempts to reflect on what we have are all going it alone, having to define their own model and their own builders for describing what stuff is. You've mentioned 5 major areas where reflection is a core part of the mission, and each of these have multiple implementations.

There is the old TypeScript type emitter, reflect-metadata, which would provide some type information at runtime, but it targets very old decorator and metadata specifications, not the current version. I don't super know how accurate or complete it's model really is, how closely it writes down what typescript knows versus how much it defines its own model to export to. https://www.npmjs.com/package/reflect-metadata

We are maybe at the cusp of some unifying, some coming together, albeit not via typescript at this time, still as a separate layer. The Standard Schema project has support from I dare say most of the top validation libraries. But extending this to API definitions, ORM tools is in extremely early stages. https://github.com/standard-schema/standard-schema?tab=readm...

But that’s the whole point of something like this. You do it once and dynamically generate everything else downstream. So change it once in the zod schema and it propagates with type checking through your entire app.

The zod schema becomes the source of truth.

> It's so frustrating how full-stack development requires so many ways of describing the same shapes: JS input validation, Swagger for API definition, server-side input validation, ORM for schema conformance, and TypeScript often requiring separate definitions on server and client side. It's so tedious.

Many of the same people who complain about how complicated modern web dev is would also shudder at the suggestion to just replace all those things with TypeScript (and Zod, if that's your TS schema definition and validation library of choice).

All APIs are experimental and in a state of constant flux and evolution, including the web.

The only time status quo is fine is when it's for clients and employers who just want stuff done and don't care how.

In that context, all these unfortunate layers of complexity at least mean more billable hours.

How else would you do it? You could use something like trpc for full end to end type safety but that requires using TypeScript on both the frontend and backend (which not everyone does) and also locking yourself into only the web platform (so no mobile, etc).

Yes there should at least be a way to consolidate so that we can agree on format to treat as the source of truth that we can generate the other formats from.

We use drizzle + Hono + client with zod. So the entire chain from ui to client to server to DB follow same validation and shape.

Well, Zod isn't just for validating JSON. It supports validating objects that can't be represented in JSON without transformation (dates, class instances, and so on). You can also use it as your JSON transformer if you want to - you can write your schema so it accepts strings, validates them as ISO date strings, and outputs Date objects, for instance.

Zod 4 supports converting a Zod schema to JSON-Schema (natively, this has always been possible with 3rd-party libs).

One key difference is preprocessing/refine. With Zod, you can provide a callback before running validation, which is super useful and can't be represented in JSON. This comes in handy more often than you'd think - e.g converting MM/DD/YYYY to DD/MM/YYYY before validating as date.

It is a good choice and in that case TypeBox is a decent way to generate it.

And you can use AVJ or its own schema validation system (which is much faster, but only sync where avj has asynchronous validation options in case you want to check against a database or something).

JSON Schema is the way for cross-language validation. Wrap it in OpenAPI and you also get nice API docs for free.

Yeah, it's a nice route. There's no way I could afford to do an all or nothing migration for something like validation.

The TypeScript compiler is only needed during development, the compiled JavaScript code contains no TypeScript-specific logic. Zod’s validation is entirely JavaScript-based, relying on simple checks (e.g., typeof, regexes, comparisons).

Also, the 2kb bundle just for the zod/v4-mini package, the full zod/v4 package is quite large.

I think Zod uses JIT compilation via `new Function`, rather than including the entire TypeScript compiler. This method allows for concise validation logic, executing only what’s necessary at runtime.