In Zod, .optional() lets a key be missing, .nullable() lets its value be null, and .nullish() allows both. They are not interchangeable: an optional field still rejects null, and a nullable field still requires the key to be there. Pick the one that matches what your API actually sends, because JSON has two different ways of saying "no value" and Zod checks them separately.

If you are starting from a sample response, the FindUtils JSON to Zod Schema tool writes the first draft of the schema in your browser. It turns every null it sees into z.null(), so this choice is the first edit you will make.

JSON Has Three States, Not Two

A key in a JSON object can be in one of three states:

StateJSONMeaning in most APIs
Present with a value{ "discount": 5.5 }The value is known
Present as null{ "discount": null }The value is known to be empty
Absent{}Not sent, not known, or not changed

null is one of JSON's literal values (RFC 8259). undefined is not. When JavaScript serializes an object, JSON.stringify() drops properties whose value is undefined: JSON.stringify({ a: undefined, b: null }) gives {"b":null}. So on the wire, "undefined" always shows up as a missing key.

What Each Modifier Accepts

We ran the same four inputs through Zod 3.25.76 and Zod 4.6.7 with a schema of z.object({ a: z.string().<modifier>() }). Both versions gave the same results:

Input.optional().nullable().nullish()
{ "a": "x" }passespassespasses
{} (key missing)passesfailspasses
{ "a": null }failspassespasses
{ a: undefined } (in JavaScript)passesfailspasses

The inferred TypeScript types follow the same logic, as the Zod API docs describe:

  • z.string().optional() gives string | undefined, and inside z.object() the key becomes a?: string.
  • z.string().nullable() gives string | null, and the key is required.
  • z.string().nullish() gives string | null | undefined, and the key is optional.

Which One Should You Use?

API responses

Match the server's contract. If the server always sends the key and uses null for "no value", use .nullable(); that also catches a server bug that drops the key. If the server leaves the key out instead, use .optional(). Use .nullish() only when you have actually seen both, for example during a migration between two API versions, because it hides the difference.

To find out which you have, compare a few real responses in JSON Diff and look for keys that are null in one and missing in another.

PATCH request bodies

Here the three states mean three different things. RFC 7396 (JSON Merge Patch) defines a missing key as "leave this field alone" and null as "remove this field". A schema for such a body needs .nullish() on the editable fields, and your code then has to check "discount" in body or body.discount === undefined before it decides between "skip" and "clear". Collapsing both into one value loses the user's intent.

Forms

HTML inputs do not produce null. An empty text field gives an empty string "", which passes z.string(), .optional() and .nullable() alike. If an empty field should count as "no value", say so explicitly, for example with .min(1) for a required field or a transform that turns "" into undefined before an optional check.

Defaults Do Not Catch null

.default() fills in a value only when the input is undefined. In our tests on both versions:

  • z.object({ a: z.string().default("none") }) turned {} into { "a": "none" }.
  • The same schema rejected { "a": null }.
  • z.string().nullable().default(null) turned {} into { "a": null }, which is a common way to make a response object always have the key.

If you want both null and a missing key to end up as one value, use .nullish() with a transform, such as .nullish().transform((v) => v ?? null). It turns {} into { "a": null }.

A Quick Decision Rule

  1. Look at real payloads, not documentation examples.
  2. Key sometimes missing, never null: .optional().
  3. Key always present, sometimes null: .nullable().
  4. Both, or a PATCH body where they mean different things: .nullish(), and handle the two cases in code.
  5. Never use z.null() on its own for a field that can ever hold a value.

FAQ

Does .optional() accept null in Zod?

No. .optional() accepts a missing key or undefined. A null value fails with an "expected string, received null" error in both Zod 3 and Zod 4.

What is the difference between .nullish() and .optional().nullable()?

They accept the same inputs: a value, null, undefined or a missing key. .nullish() is the shorter way to write it.

Why does .default() not replace null?

Because a default applies only when the input is undefined. A null is a real input and has to pass the inner schema. Use .nullable().default(null) or a transform if null should also be replaced.

How do I make every field optional at once?

Call .partial() on the object schema. Every key then accepts a missing value, but still rejects null unless you also add .nullable().

Need help with a project? The team behind FindUtils takes on freelance work through Upwork, including a fast React front end for your web app, dashboard or admin panel.

Sources