Repository navigation
fix: preserve unique tags with defaulted discriminators - #6582
Conversation
There was a problem hiding this comment.
🔵 Needs a closer look
The public lookup ambiguity contract still needs documentation, so final human approval is warranted.
Pull request overview
Preserves explicit discriminator routing when multiple union members default to undefined, while rejecting ambiguous missing tags.
Changes:
- Centralizes discriminator-map construction and ambiguity handling.
- Preserves nested-union metadata and compiler fallback behavior.
- Adds regression coverage for defaults, collisions, lookup, nesting, and duplicates.
File summaries
| File | Summary |
|---|---|
packages/zod/src/v4/core/schemas.ts |
Implements ambiguity-aware discriminator handling. |
packages/zod/src/v4/core/compile.ts |
Preserves interpreter fallback for collisions. |
packages/zod/src/v4/classic/tests/discriminated-unions.test.ts |
Adds comprehensive regression tests. |
Review details
Suppressed comments (1)
packages/zod/src/v4/core/schemas.ts:2640
- This new branch makes a previously valid schema state throw when the caller asks for an ambiguous
undefined, butgetDiscriminatedOption's public type and docs still describe every declared discriminator value as returning an option (for example, two optional members makeundefineda declared value). Please document the ambiguity/error contract in the public API and the helper's JSDoc so callers do not assume a declared value is always retrievable.
if (option === null) throw new Error(`Ambiguous discriminator value "${String(value)}"`);
- Files reviewed: 3/3 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
Important
Nested discriminator metadata can silently misroute backward encoding; this should be addressed before merging.
Reviewed changes Reviewed the runtime map semantics, getDiscriminatedOption() alignment, compiler fallback, nested-union metadata, and the added behavior tests.
- Ambiguous
undefineddispatch — duplicate absent-value claims no longer block unique explicit tags, while other duplicate values remain schema errors. - Shared lookup behavior — runtime parsing and
getDiscriminatedOption()now use the same map construction and reject ambiguous lookup. - Nested and compiled unions — nested metadata omits forward-unroutable
undefined, and compiler collisions continue through interpreter fallback. - Regression coverage — tests exercise wrapper variants, option order, synchronous and asynchronous parsing, lookup, nesting, and
unionFallback.
GPT Sol | 𝕏
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes Reviewed the full PR through f1f96bea, including the follow-up that resolves the prior nested-encoding finding.
- Ambiguous absent tags — repeated
undefinedclaims now reject ambiguous input without disabling direct dispatch for unique explicit tags. - Nested encoding — backward parsing bypasses forward-only dispatch for an absent tag, allowing ordinary union matching to reach the correct codec-backed member.
- Shared contracts —
getDiscriminatedOption(), nestedpropValues, compiler fallback, and public documentation remain aligned with the runtime policy. - Regression coverage — exact sync and async assertions cover the original compatibility case, non-
undefinedcollisions, nested forward routing, and the previously failing backward-encoding path.
GPT Sol | 𝕏

Preserve explicitly tagged parsing when multiple discriminated-union members have defaulted tags. A shared map builder marks colliding
undefinedvalues as ambiguous; missing tags fail validation, while unique tags retain direct dispatch. Other duplicate values remain schema errors.There are no schema-type checks, wrapper walks, new options, or new instance properties. The lookup helper uses the same map builder and rejects ambiguous lookup. Nested unions omit an unroutable
undefinedfrom their discriminator metadata; backward encoding ofundefineduses the existing union fallback so forward-only metadata cannot select the wrong sibling. Defined tags retain their encoding fast path. The compiler keeps its existing interpreter fallback for collisions rather than introducing a second dispatch policy.Local build, lint, resolution, integration, and the full suite pass, including 8,243 tests on each of TypeScript 5.5.4, 6.0.3, and 7.0.2. Plain-Node ESM/CJS probes pass for both classic and Mini. The encoding regression has synchronous and asynchronous coverage, and the API reference documents ambiguous lookup.
Runtime measurements on
f1f96beause ten interleaved rounds, alternating which revision runs first, fixed iteration counts, and GC between samples. Host load stayed at 5.44–6.10; no meaningful runtime regression was observed. Earlier high-load timing samples were discarded. The initial broad memory run also showed a +288 B union result that did not reproduce in two isolated comparisons; the 500-resource catalogue remained approximately 38.53 MiB on both revisions.Closes #6577.