Zod 4

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)

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.

this blog post was a delight to read. great work, colin && thanks!!

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

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

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

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?

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

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)

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

Would be

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

And a query with just { user { username } } would have the posts property omitted entirely.

Either Unions, or optional fields

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

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.

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

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

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.

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.

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

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

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.

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.

Can you elaborate?

Or maybe 3.8-q4_K_M for a quantized version

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

What do you use for validation in TS? Anyone who deals with data should be validating/parsing it.

  const cached = new Map<string, Function>()

  export function as<T>(o: any, path: string, as: (o: any) => T | undefined) {
    try {
      let fn = cached.get(path)
      if (!fn) cached.set(path, fn = new Function('o', `return o.${path}`))
      const v = fn(o)
      return as(v) as T | undefined
    }
    catch (e) {
      return undefined
    }
  }

  as.number = (o: any) => (typeof o === 'number' ? o : undefined)
  as.string = (o: any) => (typeof o === 'string' ? o : undefined)
  as.boolean = (o: any) => (typeof o === 'boolean' ? o : undefined)
  as.numbers = (len = 0) => (o: any) => (o instanceof Array && o.length >= len && o.every(c => typeof c === 'number') ? o : undefined)
  as.strings = (len = 0) => (o: any) => (o instanceof Array && o.length >= len && o.every(c => typeof c === 'string') ? o : undefined)


  const size = as(usrConfig, 'sys.size', as.numbers(2))
  const fontpath = as(usrConfig, 'sys.font', as.string)

    let someArray = [1, 2, , 4];
    console.log(as.numbers(someArray) === someArray); // => true
    
    for (let number of numbers) {
        // This should be safe because I know everything in the array is a number, right?
        console.log(number.toFixed(2)); // => TypeError: number is undefined
    }

If you don't do web dev (or at least, the latest web dev) then it's understandable, I often see lots of posts in the top spots whose languages I have no idea about either.

Zod is quite common, if not the most used validation library for JS/TS projects.

When I see a repository with many files "updated 4 years ago" I'm usually inclined to think it's abandoned.

Also, I think teflon pans are much better than squids.

Ah yes two totally different technologies - let's compare them like they're designed to solve the exact same problem