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!

> 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.

This is extremely sensible. And it means you can provide security updates for older versions, just all in the same codebase's releases.

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)

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?)

Just would like to say I really appreciate your consideration of releasing breaking changes. I know not all libraries can employ your methodology but I wish many more of them would, as a frontend platform engineer.

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

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

A heartfelt thank you for not breaking the world like many other libraries do!

Breaking changed in fundamental but auxiliary libraries are so painful in the world of frontend development that it's not even funny anymore.

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?

This isn't an npm exclusive issue. A dependency having some other transitive deps also depend on an older version is a problem that happens in literally every other ecosystem. If anything, npm gives you more escape hatches by actually allowing you to run multiple versions concurrently if you need to or selectively overriding parts of your transitive dependency graph.

What package management system has a solution to this? Even so called "stable" platforms like Maven deal with this nonsense by publishing new versions under a new namespace (like Apache Commons did from v2 to v3).

Horrible, not going to use it now. My ide will import whichever interchangeably, and it'll be a mess

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 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.

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
            }>
        }
    }

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.

Either Unions, or optional fields

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.

You shouldn’t typically need to redefine your data all over the places. There are zillions of converters for everything to zod, and zod to everything.

If you already have JSON schema/swagger schemas, generate zod from em. If you use a typescript orm, I bet you $10 there’s a zod generator for it.

Honestly zod has gotten so popular that for me, it’s the unifying schema definition that everything else in the stack can rely on. And since directly defines the types, devs actually keep it up to date (swagger docs at my company are ALWAYS lagging behind changes)

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.

> 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).

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

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.

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?

Why ArkType over TypeBox?

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

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.

I worked on two large projects that use Zod and Protobuf to ensure schema evolution goes well with 5+ teams. Even if you have a lightweight frontend, it makes sense to use something that validates the schemas in the backend.

In the end you'll have a schema somewhere. Maybe defined in the database system, maybe defined in the models of an object-relational mapper. Since defining the schemas in database system or using object-relational mappers can cause very difficult problems in large projects we do not use it and use Zod and Protobuf instead. While I think you could even replace Protobuf completely with Zod or something similar.

There is the British Post Office scandal [1] around an IT system called Horizon (the legacy system in this case). After reading about the details I'm pretty sure something like Zod (I mean any schema validation) would have contributed to prevent this scandal. They even mentioned the lack of using a schema in the technical appendices in the court documents of the group legal action [2].

[1] https://en.wikipedia.org/wiki/British_Post_Office_scandal

[2] https://en.wikipedia.org/wiki/Bates_%26_Others_v_Post_Office...

Zod has nothing to do with SPAs and isn't just a frontend tool. Do you not validate inputs in your code?

Entire classes of problems simply don't exist, if you also close your eyes.

Well how do you do server-side validation?

Because now I have the impression that you're just defensively writing a bunch of if-statements. Or worse, you rely on html client-side form validation only.

We have an enormous number of backend-only Zod schemas that are used as part of our data pipelines; so it doesn't seem like something that only exists to solve SPA problems.

What's your SaaS? I would like to check out your use case that allowed you to build a great product without SPA.

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.

You might like Typia better.

I recently put together a deck for this after some investigation: https://docs.google.com/presentation/d/1fToIKvR7dyvQS1AAtp4Y...

On the ArkType website they talk about speed and DX, but no mention of bundle size. I assume, and maybe this is an unfair assumption, that's because it's bad. I haven't come across ArkType until just now, but I was just checking out Valibot today because it's got a small bundle size.

We also chose ArkType after evaluating Zod, Valibot, and Effect Schema, among others. It seemed to have the best developer experience while also being much faster. It also supports the Standard Schema project which I believe Effect Schema does not fully support.

Everyone else is using Zod so the LLMs understand it well, there’s a big ecosystem, it’s unlikely to disappear overnight, and new hires may well already use it. It’s the boring solution.

I came here to say this. I clicked on the link and had no idea what this was about.