i/pydantic_extra_types_coordinate/)
      * [ Mac Address  ](../../api/pydantic_extra_types_mac_address/)
      * [ ISBN  ](../../api/pydantic_extra_types_isbn/)
      * [ Pendulum  ](../../api/pydantic_extra_types_pendulum_dt/)
      * [ Currency  ](../../api/pydantic_extra_types_currency_code/)
      * [ Language  ](../../api/pydantic_extra_types_language_code/)
  * Examples  Examples 
    * [ Secrets  ](../../examples/secrets/)
  * Error Messages  Error Messages 
    * [ Error Handling  ](../../errors/errors/)
    * [ Validation Errors  ](../../errors/validation_errors/)
    * [ Usage Errors  ](../../errors/usage_errors/)
  * Integrations  Integrations 
    * [ Mypy  ](../../integrations/mypy/)
    * [ PyCharm  ](../../integrations/pycharm/)
    * [ Hypothesis  ](../../integrations/hypothesis/)
    * [ Visual Studio Code  ](../../integrations/visual_studio_code/)
    * [ datamodel-code-generator  ](../../integrations/datamodel_code_generator/)
    * [ devtools  ](../../integrations/devtools/)
    * [ Rich  ](../../integrations/rich/)
    * [ Linting  ](../../integrations/linting/)
  * [ Blog  ](https://blog.pydantic.dev/)
  * [ Pydantic People  ](../../pydantic_people/)

Page contents

  * Union Modes 
    * Left to Right Mode 
    * Smart Mode 
  * Discriminated Unions 
    * Discriminated Unions with str discriminators 
    * Discriminated Unions with callable Discriminator 
    * Nested Discriminated Unions 
  * Union Validation Errors 

#  Unions

Unions are fundamentally different to all other types Pydantic validates -
instead of requiring all fields/items/values to be valid, unions require only
one member to be valid.

This leads to some nuance around how to validate unions:

  * which member(s) of the union should you validate data against, and in which order? 
  * which errors to raise when validation fails? 

Validating unions feels like adding another orthogonal dimension to the
validation process.

To solve these problems, Pydantic supports three fundamental approaches to
validating unions:

  1. left to right mode  \- the simplest approach, each member of the union is tried in order and the first match is returned 
  2. smart mode  \- similar to "left to right mode" members are tried in order; however, validation will proceed past the first match to attempt to find a better match, this is the default mode for most union validation 
  3. discriminated unions  \- only one member of the union is tried, based on a discriminator 

##  Union Modes  ¶

###  Left to Right Mode  ¶

Note

Because this mode often leads to unexpected validation results, it is not the
default in Pydantic >=2, instead ` union_mode='smart' ` is the default.

With this approach, validation is attempted against each member of the union
in their order they're defined, and the first successful validation is
accepted as input.

If validation fails on all members, the validation error includes the errors
from all members of the union.

` union_mode='left_to_right' ` must be set as a [ ` Field ` ](../fields/)
parameter on union fields where you want to use it.

Union with left to right mode

    
    
    from typing import Union
    
    from pydantic import BaseModel, Field, ValidationError
    
    
    class User(BaseModel):
        id: Union[str, int] = Field(union_mode='left_to_right')
    
    
    print(User(id=123))
    #> id=123
    print(User(id='hello'))
    #> id='hello'
    
    try:
        User(id=[])
    except ValidationError as e:
        print(e)
        """
        2 validation errors for User
        id.str
          Input should be a valid string [type=string_type, input_value=[], input_type=list]
        id.int
          Input should be a valid integer [type=int_type, input_value=[], input_type=list]
        """
    

The order of members is very important in this case, as demonstrated by tweak
the above example:

Union with left to right - unexpected results

    
    
    from typing import Union
    
    from pydantic impo