Attach human-readable descriptions to schemas
Schema documentation
Zod · Module
.describe
.describe() registers a schema description in Zod's global registry and returns a new schema instance. Zod recommends .meta() for new metadata because it supports the broader metadata API.
How it works
.describe() creates a new schema instance and registers it in z.globalRegistry with a description field. It remains supported, although the documentation recommends .meta() for new metadata because it provides a broader metadata API.
Syntax
schema.describe(description)Parameters
| Name | Type | Description |
|---|---|---|
description | string | The text to register as the schema description. |
Returns
A new schema instance registered in z.globalRegistry with the supplied description.
Key points
.describe(text)stores the supplied text as the schema'sdescriptioninz.globalRegistry.- Calling
.describe()produces a new schema instance, preserving Zod's immutable method style. - It can be chained directly after a schema constructor, such as
z.email(). - Pass the description as a string argument to document the schema.
- The equivalent
.meta()call uses an object containing adescriptionproperty.
Common mistakes
.describe()is supported, but prefer.meta()when adding metadata in new code.
Example: Describe a schema
import { z } from "zod";
const emailSchema = z.email().describe("An email address");
console.log(z.globalRegistry.get(emailSchema));
// { description: "An email address" }Registers a description for the schema, which can then be read from Zod's global registry.
When to use it
Expose descriptions to tools that read Zod registry metadata
Metadata-driven tooling
Provide descriptive metadata for downstream schema-documentation workflows
API contract generation
Interview questions
QWhat does .describe() do?
.describe() is shorthand for registering a schema in z.globalRegistry with only a description field. The description can be retrieved from that registry.
Follow-up: How would you attach multiple metadata fields? Use .meta({ ... }), which is the recommended approach for metadata.
QDoes .describe() mutate the schema?
It returns a new schema instance rather than mutating the original schema. The new instance is registered globally with its description.
Follow-up: What other behavior should be checked when chaining schema methods? Verify whether each method returns a new instance or the original schema.
QWhat is the .meta() equivalent of .describe()?
For an email schema, emailSchema.describe("An email address") is equivalent to emailSchema.meta({ description: "An email address" }). Both associate the description with the schema through the global registry.
Follow-up: Why might .meta() be preferable? It supports metadata beyond a description and is the documented recommendation.
Related
.meta()z.globalRegistryz.email()