UnionSchema

This class defines the schema for union types, allowing a value to be validated against multiple potential sub-schemas. It supports different validation modes such as 'smart' or 'left-to-right' and provides options for automatic simplification of single-element unions and custom error reporting. The schema also includes standard configuration fields for strictness, references, and serialization behavior.

Attributes

Attribute	Type	Description
type	Literal['union']	A required literal string identifying the schema as a union type.
choices	`list[CoreSchema	tuple[CoreSchema, str]]`
auto_collapse	bool = true	Whether to automatically collapse unions with one element to the inner validator.
custom_error_type	str	The specific error type identifier to be raised when validation fails for all union choices.
custom_error_message	str	A user-defined error message string to override the default failure message.
custom_error_context	`dict[str, str	int
mode	Literal['smart', 'left_to_right'] = 'smart'	Determines the validation strategy, either attempting to find the best match or processing choices sequentially.
strict	bool	Whether to enforce strict type checking and disallow data coercion during validation.
ref	str	An optional identifier used for creating recursive schemas or referencing this schema elsewhere.
metadata	dict[str, Any]	A dictionary for storing arbitrary application-specific data that does not affect validation.
serialization	SerSchema	Configuration defining how the union should be handled during data serialization.

---

Methods

---

type()

def type() - > Literal['union']

Specifies the schema type as a union, indicating that the data must validate against one of several possible schemas.

Returns

Type	Description
Literal['union']	The literal string 'union' identifying this schema type.

---

choices()

def choices() - > list[CoreSchema | tuple[CoreSchema, str]]

Defines the list of possible schemas or tagged schemas that the input data can be validated against.

Returns

Type	Description
`list[CoreSchema	tuple[CoreSchema, str]]`

---

auto_collapse()

def auto_collapse() - > bool

Determines whether to automatically simplify the union to its inner validator if only one choice is provided.

Returns

Type	Description
bool	A boolean flag indicating if auto-collapse is enabled; defaults to true.

---

custom_error_type()

def custom_error_type() - > str

Sets a specific error type identifier to be raised when validation fails for all union choices.

Returns

Type	Description
str	The string identifier for the custom error type.

---

custom_error_message()

def custom_error_message() - > str

Provides a user-defined error message to be displayed when none of the union members match the input.

Returns

Type	Description
str	The custom error message string.

---

custom_error_context()

def custom_error_context() - > dict[str, str | int | float]

Supplies additional metadata or variables to be interpolated into the custom error message.

Returns

Type	Description
`dict[str, str	int

---

mode()

def mode() - > Literal['smart', 'left_to_right']

Controls the validation strategy, choosing between 'smart' matching or 'left_to_right' sequential attempts.

Returns

Type	Description
Literal['smart', 'left_to_right']	The validation mode string; defaults to 'smart'.

---

strict()

def strict() - > bool

Enforces strict validation rules across all union choices, preventing type coercion during the matching process.

Returns

Type	Description
bool	A boolean indicating if strict mode is active.

---

ref()

def ref() - > str

Assigns a unique string identifier to the schema for use in recursive definitions or shared references.

Returns

Type	Description
str	The unique reference string for this schema.

---

metadata()

def metadata() - > dict[str, Any]

Stores arbitrary application-specific data associated with the union schema that does not affect validation.

Returns

Type	Description
dict[str, Any]	A dictionary containing custom metadata fields.

---

serialization()

def serialization() - > SerSchema

Configures how the union should be processed during the serialization of data back to its raw format.

Returns

Type	Description
SerSchema	The serialization schema configuration object.

---