Reading default values from a schema

[ravinggenius]

I'm building a search form, and the schema for it is defined as the following:

const RAW_SEACH_QUERY = z.object({
	q: z.string().optional().default("").catch(""),
	o: z.coerce.number().nonnegative().int().optional().default(0).catch(0),
	l: z.coerce
		.number()
		.nonnegative()
		.int()
		.max(MAX_PAGE_SIZE)
		.optional()
		.default(DEFAULT_PAGE_SIZE)
		.catch(DEFAULT_PAGE_SIZE),
	e: z.coerce
		.boolean()
		.optional()
		.default(DEFAULT_EXPAND_VERSIONS)
		.catch(DEFAULT_EXPAND_VERSIONS),
	v: z.enum(["list", "table"]).optional().default("list").catch("list")
});

This is further processed with .transform() step, but that's not relevant to my question. I'd really like access to the default values and the catch fallback values too. I tried the following, but it doesn't work:

RAW_SEACH_QUERY.shape.q.defaultValue();

I would expect something like .defaultValue() (and .catchFallback()) to be available. I asked ChatGPT. It suggested RAW_SEACH_QUERY.shape.q._def.defaultValue(), but .defaultValue() isn't defined. Worse I assume _def isn't part of the public API, so using it is likely not supported.

Is there a (supported) way to access the default values that I'm just missing?

[agammann]

For the schema you posted, the public parsing API gives you the defaults without inspecting _def:

const defaults = RAW_SEACH_QUERY.parse({});
const qDefault = RAW_SEACH_QUERY.shape.q.parse(undefined);

For example, with DEFAULT_PAGE_SIZE = 20 and DEFAULT_EXPAND_VERSIONS = false, the first result is:

{ q: '', o: 0, l: 20, e: false, v: 'list' }

Use the untransformed RAW_SEACH_QUERY for this, since parsing a schema with .transform() runs that transformation too. This empty-object approach works here because every field can supply a default.

Default values and catch values have different triggers: .default() handles undefined, whereas .catch() handles validation failure. So parse({}) doesn't retrieve a distinct catch fallback:

const field = z.string().default('default value').catch('fallback value');
field.parse(undefined); // 'default value'
field.parse(123);       // 'fallback value'

If the form needs the catch values as data, define those values separately and pass them into .catch(). That also works when the fallback depends on context, rather than trying to extract it from a wrapped schema.

I checked these examples and your field chains with Zod 3.24.2, 3.25.76, and 4.6.5. The docs describe the default and catch behavior.