Optional not working

[thany]

Please consider this schema:

const schema = z.object({
  email: z.email().max(254),
  firstName: z.string().max(40).optional(),
  lastName: z.string().max(80),
});

Or like this, same problem:

const schema = z.object({
  email: z.email().max(254),
  firstName: z.optional(z.string().max(40)),
  lastName: z.string().max(80),
});

Why is firstName not optional?

const optional = schema.shape['firstName'].safeParse(undefined).success;

This will be false. Why? The documentation says either of the above are the way to make something optional. It also says optional means it accepts undefined, which is what I'm testing for. And the deprecation warning clearly says safeParse(undefined) is the way to do it correctly.

And yet if I check:

const type = schema.shape['firstName'].def.type;

That will be "nonoptional". How does it arrive at there?

So what is going on? The documentation is so crystal clear on this, and yet, somehow, I'm doing something wrong apparently. What is actually the way to make something optional please?

[dosubot[bot]]

You're running into a common point of confusion with Zod's internals. When you use .optional() (or z.optional(), though that's deprecated), the field schema should be wrapped in a ZodOptional instance, which means safeParse(undefined) on that field should succeed and its .def.type should be "optional" docs code.

If you're seeing .def.type as "nonoptional" and safeParse(undefined) returns false, it's likely you're accidentally inspecting the inner schema (the value of .innerType inside ZodOptional) rather than the wrapper itself. The correct way to check is to use safeParse(undefined) directly on the field schema from the object's shape, not on its inner type see test.

Here's how you can verify:

const isOptional = schema.shape['firstName'].safeParse(undefined).success; // should be true
const type = schema.shape['firstName']._zod.def.type; // should be "optional"

If isOptional is false and type is "nonoptional", double-check that you're not accessing schema.shape['firstName'].innerType or similar. You want the top-level field schema, which should be a ZodOptional instance see issue.

The most reliable way to check if a schema is optional is to use safeParse(undefined)—this is what Zod maintainers recommend, and it's how the deprecated .isOptional() method worked internally see maintainer comment.

If your question is answered, please close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[thany]

I'm not accidentally inspecting the inner type. If I literally paste that code right under my schema definition, it does the exact opposite of what you claim it should be.

isOptional will be false
type will be "nonoptional"

So now what?

[thany]

Btw I can see the typescript type of firstName is z.ZodOptional<z.ZodString>, so that at least is working. Now as for the runtime...

[dosubot[bot]]

The TypeScript type for firstName is correct, but if safeParse(undefined) is returning false and .def.type is "nonoptional" at runtime, this strongly suggests a version mismatch or import issue in your environment. Zod's implementation guarantees that a schema created with .optional() should accept undefined at runtime and have .def.type set to "optional" (source).

Can you share your exact Zod version from package.json and show how you're importing Zod in your code? Also, at runtime, does schema.shape['firstName'] have a _zod property, a _def property, or both? This will help pinpoint if you're mixing Zod 3 and Zod 4, which can cause this kind of divergence (docs).

If you can provide a minimal reproducible example (including your import statements and how you're running the code), I can help you debug further.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[thany]

It was because I had required() called on the whole object. I thought optional() on a field would exclude it from being required.

Maybe add to the documentation that required() on an object makes it ignore optional() on any field?