Zod v4 Schema Validation

Zod v4 Schema Validation

TypeScript-first schema validation library with static type inference. This skill covers v4 patterns including the metadata registry system.

Schema Annotations

Zod v4 stores metadata in registries (primarily z.globalRegistry). Use .meta() as the primary API and .describe() as shorthand for description-only cases.

IMPORTANT: Always call .meta()/.describe() last in the method chain. Methods like .min(), .optional(), .extend() return new schema instances, so metadata must be attached at the end.

// ✅ Correct - .meta() at end of chain
z.string()
  .min(1)
  .max(100)
  .meta({ description: "User's full name", label: "Name" });

// ✅ Correct - .describe() shorthand for description only
z.string().email().describe("Primary email address");

// ❌ Wrong - metadata lost because .optional() creates new instance
z.string().meta({ description: "Lost!" }).optional();

Annotating object properties:

const userSchema = z.object({
  email: z.string().email().meta({
    description: "Used for login",
    label: "Email Address",
    placeholder: "[email protected]",
  }),
  age: z.number().min(0).describe("User's age in years"),
});

API guidance:

• Use .meta(obj) for structured metadata (title, description, examples, UI hints)