Validate a fixed discriminator
Discriminated object variants
Zod · Function
z.literal
z.literal(value) validates one exact literal value, such as a string, number, bigint, or boolean. The resulting schema infers the corresponding TypeScript literal type and rejects other values.
How it works
z.literal(value) creates a schema whose accepted input is one exact literal value. Zod infers that same literal type, and parsing succeeds only when the input matches it; use z.null() or z.undefined() for those JavaScript values.
Syntax
z.literal(value)Parameters
| Name | Type | Description |
|---|---|---|
value | string | number | bigint | boolean | The exact literal value the schema should accept; the current API documents strings, numbers, bigint values, and booleans. |
Returns
A Zod schema that accepts only the supplied literal value and infers the corresponding TypeScript literal type.
Key points
- Use literals when a value must equal one exact compile-time constant, such as a status string or numeric code.
- A string literal schema is declared by passing the exact string to
z.literal. - Numeric constants can be validated with the same constructor.
- Boolean literal values are supported.
Example: Validate an exact literal
import { z } from "zod";
const status = z.literal("success");
console.log(status.parse("success")); // "success"
// status.parse("error"); // throws a ZodError
The schema accepts exactly the string literal "success" and rejects other values.
When to use it
Enforce an exact status or code
Protocol and API values
Allow one constant setting
Configuration constraints
Interview questions
QWhat does z.literal() validate?
z.literal("tuna") accepts only the exact string "tuna"; other strings fail validation. Its inferred TypeScript type is the string literal type "tuna".
Follow-up: How would you model several permitted constants? Use z.union with separate literal schemas, or use the multiple-value form documented in the current Zod 4 API when appropriate.
QWhich values can a literal schema represent?
Literal schemas can represent exact strings, numbers, bigint values, and booleans. The schema is useful when a field must carry a discriminator or another fixed constant.
Follow-up: How can nullability be represented? Compose the literal with z.nullable() or use z.null() as the null schema, rather than treating null as an ordinary literal argument.
QHow can you retrieve the value represented by a literal schema?
The schema exposes the literal value through its .value property, so a schema such as z.literal("tuna") has .value equal to "tuna". This can be useful when code needs to inspect the declared constant.
Follow-up: How can a literal be made optional? Wrap it with z.optional(...) or call .optional() on the literal schema.
Related
z.unionz.enumz.nullz.undefinedz.optionalz.templateLiteral