Effortless Declarative data validation with Pydantic: smarter, cleaner, and more reliable
In this article

Validating incoming data is critical when building modern applications. Whether you're dealing with configuration files, API inputs, or manually entered data, ensuring data integrity upfront can prevent costly errors later. This is where Pydantic comes in, a powerful library that uses Python's type hints to provide a declarative, intuitive, and efficient approach to data handling.
Why Declarative Data Validation?
Declarative programming focuses on describing what you expect rather than how to achieve it. In data validation, this means defining the structure, types, and constraints upfront while the library enforces these rules automatically.
Adopting a declarative style offers several advantages:
- Readability: The intent is clear and concise.
- Less Boilerplate: Reduces repetitive manually written validation logic.
- Consistency: Standardizes validation across your application.
With these advantages in mind, let’s see how Pydantic makes declarative validation simpler.
Introduction to Pydantic
Pydantic uses Python’s type annotations to define data validation rules. It introduces data models, which are essentially Python classes that define the structure and constraints of your data while allowing custom validators to be attached when needed.
A number of key features of the Pydantic library are listed above. Now, let’s see it in action with a real-world example.
- - -
Basic Pydantic Usage Example
Imagine we are building a resource management system that collects and processes data from edge computing devices. Given that data from various sources may be incomplete or inconsistent, we need a good way to validate it.
Consider this example of device information provided as a JSON object:
1{2 "model": "POWER EDGE",3 "serial_no": "ED-2025-455 ",4 "dimensions": ["20", " 30", "25.5"],5 "active": "yes"6}
This dataset includes some formatting inconsistencies: extra spaces, a mix of different data types within a single container, and some fields that are missing (e.g., id and device_color). Let’s see how Pydantic handles it:
1from pydantic import BaseModel234class EdgeComputingDevice(BaseModel):5 id: int | None = None6 model: str7 serial_no: str8 dimensions: list[int | float]9 device_color: str = 'black'10 active: bool111213validated_device = EdgeComputingDevice.validate_json(raw_json_string)14print(repr(validated_device))15print(f'Model: {validated_device.model}')16print(f'Dimensions: {validated_device.dimensions}')
Output:
1EdgeComputingDevice(id=None, model='POWER EDGE', serial_no='ED-2025-455 ', dimensions=[20, 30, 25.5], device_color='black', active=True)2Model: POWER EDGE3Dimensions: [20, 30, 25.5]
What’s happening here?:
- Type-based Validation: Fields like
int,str, andbooldrive validation. - Support for Complex Types:
dimensionsaccepts sequential data. - Automatic Conversion: Strings are converted to integers, and "yes" is interpreted as
True. - Default Values: Missing fields (
id, device_color) are automatically populated in the validated output. - Union Types: The
|operator supports multiple acceptable types (e.g.,int | float). - JSON Validation: Models can parse and validate JSON directly.
While this example works well, what if we need even stricter validation? Let’s refine it.
- - -
Adding Constraints and Data Transformations
Input data can be validated more precisely by enforcing constraints on fields. Additionally, it may be very beneficial to transform data during the validation. For instance, removing leading/trailing whitespaces can ensure string length constraints are meaningful. Here’s an enhanced example with additional validation rules:
1from pydantic import AfterValidator, BaseModel, Field2from annotated_types import Ge, Le, MaxLen, MinLen3from typing import Annotated456DimensionSize = Annotated[int | float, Ge(10), Le(1000)]789class EdgeComputingDevice(BaseModel):10 id: int | None = None11 model: Annotated[str, AfterValidator(str.lower),12 AfterValidator(str.strip), MaxLen(30)]13 dimensions: Annotated[list[DimensionSize], MinLen(3), MaxLen(3)]14 serial_no: Annotated[str, AfterValidator(str.strip)]15 active: bool16 device_color: Annotated[str, AfterValidator(str.lower),17 MaxLen(30)] = 'black'181920validated_device = EdgeComputingDevice(**json.loads(raw_json_string))21print(validated_device.model_dump())
Output:
1{'id': None, 'model': 'power edge', 'dimensions': [20, 30, 25.5], 'serial_no': 'ED-2025-455', 'active': True, 'device_color': 'black'}
Key improvements:
- Enhanced Validation: Enforced constraints like
MinLenandMaxLen. - Field Transformations: Used
AfterValidatorfor string trimming and case conversion. - Field Validation Pipeline: Constraints and transformations are applied in sequence.
- Serialization: Models are easily converted to dictionaries.
By enforcing these rules, we eliminate many potential data inconsistencies before they can cause issues.
- - -
Informative Validation Errors
An important aspect of data validation is knowing why a particular piece of data failed validation. Validation errors can be presented to users or checked by system administrators. Consider the following invalid input. It is missing a mandatory field, contains the wrong value types, and some values do not meet the constraints:
1{2 "serial_no": "ED-2024-103",3 "dimensions": ["not int", "3000", "25.5", "50"],4 "active": "not active",5 "color": 106}
In case of the above invalid data, Pydantic raises a ValidationError with the following human-readable information:
1pydantic_core._pydantic_core.ValidationError: 6 validation errors for EdgeComputingDevice2model3 Field required [type=missing, input_value={'serial_no': 'ED-2024-103', ...10}, input_type=dict]4 For further information visit5 https://errors.pydantic.dev/2.10/v/missing6dimensions7 List should have at most 3 items after validation, not 4 [type=too_long, input_value=['not int', '3000', '25.5', '50'], input_type=list]8dimensions.0.int9 Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='not int', input_type=str]10 For further information visit11 https://errors.pydantic.dev/2.10/v/int_parsing12dimensions.0.float13 Input should be a valid number, unable to parse string as a number [type=float_parsing, input_value='not int', input_type=str]14 For further information visit15 https://errors.pydantic.dev/2.10/v/float_parsing16dimensions.117 Input should be less than or equal to 1000 [type=less_than_equal, input_value=' 3000', input_type=str]18 For further information visit19 https://errors.pydantic.dev/2.10/v/less_than_equal20active21 Input should be a valid boolean, unable to interpret input [type=bool_parsing, input_value='not active', input_type=str]22 For further information visit23 https://errors.pydantic.dev/2.10/v/bool_parsing
Features:
- All Is Reported: Reports all errors, not just the first encountered.
- Detailed Info: Provides detailed explanations, including error location, description, invalid value, and helpful links.
- Process Errors: Offers structured error details for easier programmatic handling.
- - -
Handle Hierarchical Data
In our example, the edge device input may include an optional network field. This field value consists of hierarchically nested structures. Its data is unstructured, especially network interfaces, and contains repeated values in the IP address list.
1{2 "id": 2025139,3 "model": " POWER EDGE",4 "serial_no": "ED-2025-139",5 "device_color": "WHITE",6 "dimensions": ["20", "30", 25.5],7 "active": "TRUE",8 "network": {9 "interfaces": " eth0, eth1 ",10 "macs": ["11:22:33:44:55:66", "AA-BB-CC-DD-EE-FF"],11 "ip-addresses": ["192.168.0.1", "192.168.0.1", "192.168.16.1"]12 }13}
To handle such hierarchical data, Pydantic models should also be organized hierarchically, with one model using other models as types in field annotations. This way, even multi-level data hierarchies can be successfully adjusted according to the rules and validated.
These are validation models to handle the inputs shown above:
1from annotated_types import Ge, Le, MaxLen, MinLen2from pydantic import AfterValidator, BaseModel, BeforeValidator,3 ConfigDict4from typing import Annotated, Any567DimensionSize = Annotated[int | float, Ge(10), Le(1000)]8910def split(value: Any) -> list[str] | Any:11 if not isinstance(value, str):12 return value13 return [part for part in value.split(',') if part != '']141516class DeviceNetwork(BaseModel):17 model_config = ConfigDict(str_strip_whitespace=True, str_max_length=30)181920 mac_addresses: Annotated[list[str], Field(alias='macs')] = []21 interfaces: Annotated[list[str], BeforeValidator(split)] = []22 ip_addresses: Annotated[set[str], Field(alias='ip-addresses')] = {}232425class EdgeComputingDevice(BaseModel):26 model_config = ConfigDict(str_strip_whitespace=True, str_max_length=30)272829 id: int | None = None30 model: Annotated[str, AfterValidator(str.lower)]31 dimensions: Annotated[list[DimensionSize], MinLen(3),MaxLen(3)]32 serial_no: str33 active: bool34 device_color: Annotated[str, AfterValidator(str.lower)] = 'black'35 network: DeviceNetwork = DeviceNetwork()
Output:
1EdgeComputingDevice(id=2025139, model='power edge', dimensions=[20, 30, 25.5], serial_no='ED-2025-139', active=True, device_color='white', network=DeviceNetwork(mac_addresses=['11:22:33:44:55:66', 'AA-BB-CC-DD-EE-FF'], interfaces=['eth0', 'eth1'], ip_addresses={'192.168.16.1', '192.168.0.1'}))
Pydantic features used:
- Nested Models: Enables the use of one model as a field type within another, simplifying validation of hierarchical data.
- Default Model Behavior: Declaring the
model_configattribute eliminates repetitive use ofAfterValidator(str.strip)andMaxLen(30)for specific fields. - Field Aliases: Allows input field names to differ from model attributes, beneficial for Python-class incompatible field names (e.g.,
ip-addresses). - Field Parsing Customization: Functions such as
BeforeValidatorenable specialized input parsing, like splitting interface names from a single string. - Mutable Defaults: Pydantic safely deep-copies default field values, avoiding issues with mutable defaults (e.g., lists).
- Container Type Conversion: For fields like
ip_addresses, input lists are automatically converted to sets to eliminate duplicates. - - -
Add Cross-Field Rules and Reuse Types
The validation models presented in the previous section are still not precise enough to catch all invalid data. Malformat IP and MAC addresses or invalid color names don’t cause errors. Additionally, each network interface should have a corresponding MAC address, which is not checked.
Let's fix this in the validation models using another set of Pydantic features:
1from annotated_types import Ge, Le, MaxLen, MinLen, Predicate2from ipaddress import IPv4Address3from pydantic import AfterValidator, BaseModel, BeforeValidator,4 ConfigDict, Field5from typing import Annotated, Any, Self6from pydantic_extra_types.mac_address import MacAddress7from pydantic_extra_types.color import Color8910def split(value: Any) -> list[str] | Any:11 if not isinstance(value, str):12 return value13 return [part for part in value.split(',') if part != '']141516DimensionSize = Annotated[int | float, Ge(10), Le(1000)]17Interface = Annotated[str, Field(pattern=r'^eth\d+$')]18UniqueMembers = Predicate(19 lambda collection: len(set(collection)) == len(collection)20)212223class DeviceNetwork(BaseModel):24 model_config = ConfigDict(str_strip_whitespace=True, str_max_length=30)252627 mac_addresses: Annotated[list[MacAddress], UniqueMembers,28 Field(alias='macs')] = []29 interfaces: Annotated[list[Interface], BeforeValidator(split),30 UniqueMembers] = []31 ip_addresses: Annotated[set[IPv4Address],32 Field(alias='ip-addresses')] = {}333435 @model_validator(mode='after')36 def _check_if_each_interface_has_mac_address(self) -> Self:37 if len(self.mac_addresses) != len(self.interfaces):38 message = (39 'Number of macs must be the same as the number '40 f'of interfaces in {repr(self)}.'41 )42 raise ValueError(message)43 return self444546class EdgeComputingDevice(BaseModel):47 model_config = ConfigDict(str_strip_whitespace=True, str_max_length=30)484950 id: int | None = None51 model: str52 dimensions: Annotated[list[DimensionSize], MinLen(3), MaxLen(3)]53 serial_no: Annotated[str, Field(pattern=r'^ED-\d{4}-\d{3}$')]54 active: bool55 device_color: Color = Color('black')56 network: DeviceNetwork | None = DeviceNetwork()
Output:
1EdgeComputingDevice(id=2025139, model='POWER EDGE', dimensions=[20, 30, 25.5], serial_no='ED-2025-139', active=True, device_color=Color('white', rgb=(255, 255, 255)), network=DeviceNetwork(mac_addresses=['11:22:33:44:55:66', 'aa:bb:cc:dd:ee:ff'], interfaces=['eth0', 'eth1'], ip_addresses={IPv4Address('192.168.0.1'), IPv4Address('192.168.16.1')}))
Pydantic features:
- Model Validator: Cross-field validation is done by a decorated method having access to all model fields.
- Reuse Types: Leverage standard library types (e.g.:
IPv4Address, datetime)and Pydantic extra types (e.g.:MacAddress,Color). - Regex Pattern: Supports fine-tuned string field validation through regular expressions.
- - -
Conclusion
By leveraging type hints and constraints, Pydantic enables developers to write less code, reduce errors, and focus on features rather than debugging validation issues. Its declarative style, robust error reporting, and flexibility make it an invaluable tool for modern applications.
If you haven’t already, give Pydantic a try and see how it can simplify and enhance your next project!





