Nullable API fields
An API field may explicitly contain null while retaining validation for non-null values.
Zod · Function
z.nullable
z.nullable wraps a schema to accept its usual values plus null. It is equivalent to calling .nullable() on the inner schema.
How it works
z.nullable wraps an existing schema so that the resulting schema accepts values valid for the inner schema as well as null. The equivalent method form is innerSchema.nullable(), and the wrapped schema can be retrieved with unwrap().
Syntax
z.nullable(innerType)Parameters
| Name | Type | Description |
|---|---|---|
innerType | ZodType | The schema whose valid values should also allow null. |
Returns
A nullable schema that accepts values valid for the inner schema or null.
Key points
- It changes an existing schema so null becomes an accepted input.
- The standalone function accepts the inner schema as its argument, and the wrapped schema method is an equivalent alternative.
- When represented as JSON Schema, a nullable string includes both string and null in its type set.
- Nullable extends the accepted-type set rather than replacing the original inner schema.
Example: Nullable string
import { z } from "zod";
const nullableString = z.nullable(z.string());
console.log(nullableString.parse("hello")); // "hello"
console.log(nullableString.parse(null)); // nullCreates a schema that accepts either a string or null and validates both inputs.
When to use it
Optional data with explicit null
A form or database value is either a validated value or an intentional null.
Composed schemas
A schema is assembled from reusable validators and nullability is added at construction time.
Interview questions
QWhat does z.nullable do?
It wraps an inner schema and extends its accepted values with null. For example, z.nullable(z.string()) accepts either a string or null.
Follow-up: How would you express the same schema using method syntax? Use z.string().nullable(), which is equivalent to z.nullable(z.string()).
QWhat type does a nullable string represent?
The inner schema remains responsible for validating non-null values, while null is accepted directly. The inferred TypeScript type for a nullable string is string | null.
Follow-up: How can you recover the original schema? Call unwrap() on the nullable schema; it returns the inner schema.
QHow can z.nullable be written without the standalone function?
Use z.nullable(innerSchema) when constructing a nullable schema, or innerSchema.nullable() as the convenience form. Both produce equivalent validation behavior.
Follow-up: What is the distinction from nullish? Nullish permits both undefined and null, whereas nullable permits null in addition to the inner schema's values.
Related
.nullable()z.nullish()z.null()unwrap()ZodNullable