Skip to main content

Zod discriminatedUnion vs union

Definition​

  • z.union([A, B, …]) Generic union of unrelated schemas. (DEV Community).
  • z.discriminatedUnion("key", [A, B, …]) Union of object schemas that all contain the literal-valued property key`. (GitHub)

Input constraints​

  • union accepts any Zod types (objects, primitives, arrays, effects).
  • discriminatedUnion accepts only ZodObjects whose key field is a z.literal(...) unique to each branch.

Runtime algorithm​

  • union iterates through every branch until one succeeds; worst-case O(n) full validation of every branch.
  • discriminatedUnion reads the discriminator value once, selects the matching branch, validates only that branch; constant-time dispatch, faster on large unions. (DEV Community)

Error reporting​

  • union returns aggregated branch errors; messages can be verbose and ambiguous.
  • discriminatedUnion reports "invalid discriminator" or branch-specific errors, giving clearer feedback.

Static inference​

  • union narrows to A | B | ….
  • discriminatedUnion also gives safe narrowing when you switch on the discriminator key, mirroring TypeScript's discriminated-union narrowing.

Edge cases​

  • Overlapping discriminant literals or missing discriminator property cause schema-creation errors in discriminatedUnion; union has no such guard.
  • Nested discriminatedUnion requires .options to merge when building larger unions; union nests without helpers.

When to choose​

  • Use discriminatedUnion for object variants distinguished by a tag field—higher performance, simpler errors, safer exhaustiveness checks.
  • Use union for heterogeneous unions, non-object branches, or when no single discriminator exists.

Links to This Note