Runtime type checking
Validate an opaque token or capability represented by a JavaScript symbol before passing it to application code.
Zod · Module
z.symbol
z.symbol() creates a Zod schema for JavaScript symbols. It validates symbol values at runtime and can also be used alongside symbol-keyed object properties.
How it works
Use z.symbol() to define a schema for JavaScript symbols. Parsing succeeds for symbols and fails for non-symbol values, while the inferred TypeScript output is symbol.
Syntax
z.symbol()Returns
A Zod schema that validates JavaScript symbol values.
Key points
- Zod schemas model runtime types, so a symbol schema can be composed with larger schemas.
- Object shapes may use symbols as property keys when those keys need explicit schema coverage.
- Using a
constsymbol key lets TypeScript preserve that exact key in the inferred object type. - The value associated with a declared symbol key receives ordinary Zod validation.
Example: Validate a symbol
import * as z from "zod";
const schema = z.symbol();
const token = Symbol("token");
console.log(schema.parse(token) === token); // true
console.log(schema.safeParse("token").success); // falseCreates a schema that accepts JavaScript symbol values and rejects values of other types.
When to use it
Symbol-keyed object fields
Define object shapes that contain a declared symbol property and validate that property's value.
Schema composition
Compose symbol validation with other Zod schemas when modeling structured application data.
Interview questions
QWhat does z.symbol() validate?
z.symbol() constructs a Zod schema whose accepted values are JavaScript symbols. Calling parse returns the validated symbol when the input has that type and throws for incompatible input.
Follow-up: How would you validate a particular symbol? Use a custom refinement or related schema logic, because symbols are not handled as literal values by the documented literal mechanism.
QWhen would you use a symbol schema?
The schema is useful when an API accepts opaque symbol tokens, registry keys, or other values whose runtime type must be symbol. It provides runtime validation and corresponding TypeScript inference.
Follow-up: How should invalid input be handled without exceptions? Use safeParse, inspect its success result, and process the returned data or error accordingly.
QHow do symbol keys interact with Zod object schemas?
A declared symbol property in an object shape is tracked when the key is a const symbol, which TypeScript infers as unique symbol. Its associated value is validated like any other declared object property.
Follow-up: What happens to undeclared symbol keys? They are ignored by z.object(); the documentation specifically says loose objects do not pass them through and strict objects do not flag them.
Related
z.string()z.number()z.object()z.looseObject()z.strictObject()z.literal()safeParse()