Patch and update payloads
An API payload field can be omitted when unchanged or explicitly cleared with null.
Zod · Module
.nullish
.nullish() makes a Zod schema accept its normal values plus null and undefined. It combines nullable and optional behavior.
How it works
.nullish() creates a schema that combines the wrapped schema with both optional and nullable behavior. For example, applying it to a literal permits that literal, null, or undefined.
Syntax
z.nullish(schema)Parameters
| Name | Type | Description |
|---|---|---|
schema | Zod schema | The schema to make both optional and nullable. |
Returns
A nullish schema wrapping the supplied schema; it accepts the original schema's values plus undefined and null.
Key points
- Use nullish behavior when a field may either be omitted or explicitly set to
null. - The function form wraps an existing schema, preserving its validation rule for ordinary values.
- The resulting object is a wrapper around the original schema rather than a replacement for its underlying constraint.
Common mistakes
- It allows both absence (
undefined) and an explicit null value; it is not equivalent to nullable-only behavior.
Example: Accepting nullish input
import { z } from "zod";
const nullishYoda = z.nullish(z.literal("yoda"));
console.log(nullishYoda.parse("yoda"));
console.log(nullishYoda.parse(null));
console.log(nullishYoda.parse(undefined));The schema accepts its literal value as well as null and undefined.
When to use it
Optional configuration
A configuration value may be absent or deliberately set to null.
Data-boundary validation
A form or serialization boundary distinguishes a missing value from an explicit null.
Interview questions
QWhat does .nullish() do?
It creates a nullish version of another schema. The resulting schema accepts values valid for the original schema, plus undefined and null.
Follow-up: How would you model a value that may be null but must be present? Use .nullable() instead, because nullish behavior also permits undefined.
QWhat values can a nullish literal schema parse?
For a literal schema, z.nullish(z.literal("yoda")) accepts "yoda", null, and undefined. The original literal constraint still applies to non-nullish input.
Follow-up: What changes if the wrapped schema is z.string()? Any string is accepted, along with null and undefined.
QHow can a nullish schema be declared?
The documented function form is z.nullish(schema). The method form is also available in the related nullable API pattern, where a schema can be made nullish through a schema method.
Follow-up: When choosing between the forms, what should remain constant? The wrapped schema and resulting acceptance rules; only the construction style differs.
Related
z.nullishz.nullablenullableoptionalZodNullable