---
url: https://findutils.com/blog/zod-optional-vs-nullable-vs-nullish-null-vs-missing-keys
title: "Zod optional vs nullable vs nullish: null, Missing Keys and What Your API Really Sends"
description: "In Zod, .optional() allows a missing key, .nullable() allows null, and .nullish() allows both. How JSON represents null and absence, which one to pick for API responses, PATCH bodies and forms, and the traps we hit in tests."
category: developer
content_type: blog
cluster: json
locale: en
read_time: 7
status: published
author: "olgunozoktas"
published_at: 2026-11-11T08:08:00Z
excerpt: "JSON has null but no undefined, so a field can be present with a value, present as null, or absent. Zod gives each case its own modifier: .optional() for absent, .nullable() for null, .nullish() for both. This post shows the test matrix on Zod 3 and Zod 4, why a default does not catch null, and how to pick the right one for responses, PATCH requests and forms."
tag_ids: ["zod", "json", "typescript", "api-development", "validation"]
tags: ["Zod", "JSON", "TypeScript", "API Development", "Validation"]
primary_keyword: "zod optional vs nullable"
secondary_keywords: ["zod nullish", "zod nullable vs optional", "zod null vs undefined", "json null vs missing key", "zod default null", "zod optional null"]
tool_tag: "json-to-zod-schema"
related_tool: "json-to-zod-schema"
related_tools: ["json-to-zod-schema", "json-to-typescript", "json-diff", "json-formatter", "json-schema-validator"]
updated_at: "2026-11-11T08:08:00Z"
og_image: "/images/content/blog/zod-optional-vs-nullable-vs-nullish-null-vs-missing-keys-cover-20261111.webp"
image_alt: "Three rounded slots on a dark panel: a glowing cyan cube for a value, an empty purple outlined cube for null, and a dashed orange outline with nothing inside for a missing key."
---

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](/developers/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:

| State | JSON | Meaning 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](https://www.rfc-editor.org/rfc/rfc8259)). `undefined` is not. When JavaScript serializes an object, [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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" }` | passes | passes | passes |
| `{}` (key missing) | passes | **fails** | passes |
| `{ "a": null }` | **fails** | passes | passes |
| `{ a: undefined }` (in JavaScript) | passes | **fails** | passes |

The inferred TypeScript types follow the same logic, as the [Zod API docs](https://zod.dev/api) 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](/developers/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)](https://www.rfc-editor.org/rfc/rfc7396) 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](https://www.upwork.com/freelancers/~010a5875eab37b4bd7), including [a fast React front end for your web app, dashboard or admin panel](https://www.upwork.com/services/product/development-it-a-fast-react-front-end-for-your-web-app-dashboard-or-admin-panel-2112446421681618043).

## Related Reading

- [JSON to Zod Schema guide: generate a validator from a JSON sample](/guides/json-to-zod-schema-guide/)
- [JSON to TypeScript guide](/guides/json-to-typescript-guide/)
- [Go JSON omitempty vs omitzero: zero values, pointers and null](/blog/go-json-omitempty-vs-omitzero-zero-values-pointers-and-null/)

## Sources

- [Zod documentation: defining schemas (optionals, nullables, nullish)](https://zod.dev/api)
- [Zod 4 migration guide (changelog)](https://zod.dev/v4/changelog)
- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://www.rfc-editor.org/rfc/rfc8259)
- [RFC 7396: JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7396)
- [MDN: JSON.stringify()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
