The name of the field that holds the tag value.
An object mapping each tag value to its variant decoder.
A decoder for the union of the variant decoders' output types.
type Circle = { kind: 'circle'; radius: number };
type Square = { kind: 'square'; side: number };
const shapeDecoder = JsonDecoder.discriminatedUnion('kind', {
circle: JsonDecoder.object<Circle>({
kind: JsonDecoder.literal('circle'),
radius: JsonDecoder.number()
}),
square: JsonDecoder.object<Square>({
kind: JsonDecoder.literal('square'),
side: JsonDecoder.number()
})
});
shapeDecoder.decode({ kind: 'circle', radius: 5 }); // Ok<Circle | Square>
// A bad field reports only the matched variant's failure:
shapeDecoder.decode({ kind: 'circle', radius: 'big' });
// Err({ issues: [{ message: '"big" is not a valid number', path: ['radius'] }] })
// An unknown tag reports the expected values:
shapeDecoder.decode({ kind: 'triangle' });
// Err({ issues: [{
// message: '"kind" must be one of "circle", "square", but got "triangle"',
// path: ['kind']
// }] })
Decoder for tagged (discriminated) unions.
Unlike oneOf, which tries every branch and reports each one's failure,
discriminatedUnionis told which field carries the tag and a map from each tag value to the decoder for that variant. It reads the tag, picks the matching decoder, and delegates to it — so a failure is that variant's own structured error, with no noise from the other variants. When the tag itself is missing or unknown, it reports exactly which values were expected.When to use: prefer
discriminatedUnionover oneOf whenever your variants are objects sharing a literal "tag" field (kind,type,status, etc...). It gives precise, single-variant errors thatoneOfcannot.