how can I access schema field description

[1hachem]

in v3 I used to do something like

schema.shape[key].description

in order to access the description assigned to a field using .describe what is the equivalent in v4

[dosubot[bot]]

In Zod v4, descriptions and other metadata are no longer stored directly on schema fields, so schema.shape[key].description won't work. Instead, use the .meta() method to access metadata, including descriptions set via .describe() or .meta({ description: ... }):

const schema = z.object({
  name: z.string().describe("User's name"),
});

// Access the description:
const desc = schema.shape.name.meta()?.description; // "User's name"

If you've chained methods like .optional(), .nullable(), or .default(), call .describe() after those refinements to preserve the description. If you need to access metadata from a wrapped schema, use .unwrap():

const nameSchema = z.string().describe("User's name").optional();
const desc = nameSchema.unwrap().meta()?.description; // "User's name"

You can also retrieve descriptions from the JSON Schema output using z.toJSONSchema() if needed.

More details in the Zod v4 metadata docs and related GitHub issue.

If this answers your question, feel free to close the issue!

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[1hachem]

what a waste of energy, sorry nature 😢

[cmun2]

That still works — schema.shape[key].description reads the same in v4. What changed underneath is where it is kept: .describe() now writes into z.globalRegistry against that exact schema instance, and .description is a getter over it, so z.globalRegistry.get(schema.shape[key])?.description is the same value the long way round.

The part that bites is that the instance has to be the one you called .describe() on, and every wrapper makes a new one:

const S = z.object({
  a: z.string().describe("desc"),
  b: z.string().describe("desc").optional(),
  c: z.string().optional().describe("desc"),
});

S.shape.a.description; // "desc"
S.shape.b.description; // undefined  <- the description is on the string, not the optional
S.shape.c.description; // "desc"

.optional(), .nullable(), .default() and the rest all do this, so a field that reads as undefined usually has the description one level in. Walking innerType gets it back regardless of the order:

function describedAs(schema: z.core.$ZodType): string | undefined {
  let cur: any = schema;
  while (cur) {
    if (cur.description !== undefined) return cur.description;
    cur = cur._zod.def.innerType;
  }
  return undefined;
}

describedAs(S.shape.b); // "desc"

Worth knowing that toJSONSchema already does this walk, so if what you actually want is the description as a consumer sees it — a tool definition handed to a model, say — read it from there instead and you get the wrapped cases for free:

z.toJSONSchema(S, { io: "input" }).properties;
// a: { type: "string", description: "desc" }
// b: { type: "string", description: "desc" }
// c: { description: "desc", type: "string" }

Two smaller things. .describe("x") is .meta({ description: "x" }) with everything else left alone, so the two are interchangeable for this and .meta() is what you want if you also need title or examples. And both return a new schema rather than mutating, so const b = a.describe("x") leaves a.description as it was. Checked on 4.5.4.