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)