Docs: “no shared discriminator key → init error” statement is inaccurate in v4 beta #4332

bufferings · 2025-05-07T18:47:59Z

Hi 👋

While trying the v4 beta I noticed that the docs for z.discriminatedUnion() don’t match the current behavior.

https://v4.zod.dev/v4#upgraded-zdiscriminatedunion

If no shared discriminator key is found, Zod will throw an error at schema initialization time.

What actually happens

Each option only needs at least one discriminator field.
The discriminator keys do not have to be shared across options.
Zod throws at init time only when an option has zero discriminator fields, not when keys differ.

import { z } from 'zod';

// ✅ Works – different keys but each option has a literal
z.discriminatedUnion([
  z.object({ kind: z.literal('square'), size: z.number() }),
  z.object({ name: z.literal('rectangle'), width: z.number(), height: z.number() }),
]);

// ❌ Fails – second option lacks any literal / enum field
z.discriminatedUnion([
  z.object({ kind: z.literal('square'), size: z.number() }),
  z.object({ name: z.string(), width: z.number(), height: z.number() }), // ← error
]);
// Error: Invalid discriminated union option at index "1"

Checked with zod@4.0.0-beta.20250505T195954.

Suggested wording

If any option lacks a discriminator key, Zod will throw an error at schema initialization time.

Thanks,

The text was updated successfully, but these errors were encountered:

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: “no shared discriminator key → init error” statement is inaccurate in v4 beta #4332

Docs: “no shared discriminator key → init error” statement is inaccurate in v4 beta #4332

Docs: “no shared discriminator key → init error” statement is inaccurate in v4 beta #4332

Docs: “no shared discriminator key → init error” statement is inaccurate in v4 beta #4332

Comments

What actually happens

Suggested wording