Appearance
3.14.2 — Pydantic In Depth
A mobile app sends an order to your API. The quantity arrives as the string "2", because a form field is always text. The price arrives as "450.00". The SKU arrives as " mug-blue " with stray spaces. A second client sends "quantity": "two" and a price of -5. A third sends an extra field called discount that nobody asked for, hoping the server will apply it. Every one of these must be caught or cleaned before your business logic sees it, and the client must be told exactly what was wrong. Writing that by hand, for every field of every endpoint, is the most repetitive and error-prone code in a web service. Pydantic turns it into type hints. This page covers how Pydantic validates and converts data, every way to add your own rules, how it turns objects back into JSON, and what happens inside it.
1. The story
Samuel Colvin released Pydantic in 2017, right after Python 3.6 made variable annotations possible. His idea was simple: the type hints you already write on a class can drive run-time validation. It became popular fast, and when FastAPI arrived in 2018 it built its request handling on Pydantic.
By 2022, Pydantic was validating data in a huge share of Python services, and its pure-Python core was a bottleneck. Version 2, released in June 2023, rewrote the validation engine as a separate library, pydantic-core, written in Rust. Validation became 5 to 50 times faster. The public API changed too, which is why you will see .dict() and @validator in older code, and .model_dump() and @field_validator in new code. Everything on this page is version 2.
2. Validation and conversion
A Pydantic model is a class that inherits from BaseModel and declares fields with type hints, like a dataclass (3.13.8). The difference is what happens when you create one.
python
from decimal import Decimal
from pydantic import BaseModel, ValidationError
class OrderLine(BaseModel):
sku: str
quantity: int
unit_price: Decimal
line = OrderLine(sku="mug", quantity="2", unit_price="450.00") # (1)
print(repr(line))
print(line.quantity + 1, type(line.unit_price).__name__) # (2)
try:
OrderLine(sku="mug", quantity="two", unit_price="450") # (3)
except ValidationError as error:
print(error)text
OrderLine(sku='mug', quantity=2, unit_price=Decimal('450.00'))
3 Decimal
1 validation error for OrderLine
quantity
Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='two', input_type=str]
For further information visit https://errors.pydantic.dev/2.14/v/int_parsing(1)The strings were converted:"2"became the integer2, and"450.00"became an exactDecimal.(2)After creation, the fields really have the declared types. Your code can trust them.(3)Text that cannot become an integer is rejected, with the field name, a message, a machine-readable error type, and the bad input.
So Pydantic does two jobs at once. It validates, which means rejecting data that does not fit. And it coerces, which means converting data that can safely fit into the declared type. That second job is essential for web input, where everything starts as text.
Lax mode and strict mode
How far will conversion go? By default Pydantic runs in lax mode, which accepts a value when the conversion loses no information.
python
for value in ["2", 2.0, "2.0", 2.5]:
try:
print(repr(value), "->", OrderLine(sku="m", quantity=value, unit_price=1).quantity)
except ValidationError as error:
print(repr(value), "-> error:", error.errors()[0]["type"])text
'2' -> 2
2.0 -> 2
'2.0' -> 2
2.5 -> error: int_from_float2.0 becomes 2, because no information is lost. 2.5 is rejected rather than silently rounded, because rounding would change the order.
Strict mode turns conversion off. The value must already have the right type.
python
from pydantic import BaseModel, ConfigDict, ValidationError
class StrictLine(BaseModel):
model_config = ConfigDict(strict=True) # (1)
quantity: int
try:
StrictLine(quantity="2")
except ValidationError as error:
print("strict:", error.errors()[0]["type"])
print(StrictLine.model_validate_json('{"quantity": 2}')) # (2)text
strict: int_type
quantity=2(1)model_configholds settings for the whole model. Strictness can also be set per field.(2)A real JSON number is still accepted, because JSON has its own types.
Use lax mode for data from forms, query strings and loosely typed clients. Use strict mode for internal messages where a wrong type means a bug that should fail loudly.
3. Constraints with Field and Annotated
Types alone do not say "quantity must be between 1 and 100". Constraints do. The modern way to write them is Annotated (3.13.12), which lets you build a reusable constrained type once and use it on many models.
python
import re
from decimal import Decimal
from typing import Annotated
from pydantic import AfterValidator, BaseModel, Field, StringConstraints
def check_sku(value: str) -> str: # (1)
if not re.fullmatch(r"[A-Z0-9-]{3,20}", value):
raise ValueError("SKU must be 3-20 letters, digits or dashes")
return value
Sku = Annotated[str, StringConstraints(strip_whitespace=True, to_upper=True),
AfterValidator(check_sku)] # (2)
Quantity = Annotated[int, Field(ge=1, le=100)] # (3)
Money = Annotated[Decimal, Field(gt=0, max_digits=10, decimal_places=2)] # (4)
class OrderLine(BaseModel):
sku: Sku
quantity: Quantity
unit_price: Money
print(OrderLine(sku=" mug-blue ", quantity=2, unit_price="450.00"))text
sku='MUG-BLUE' quantity=2 unit_price=Decimal('450.00')(1)A plain function that checks a value and either returns it or raisesValueError.(2)A reusableSkutype. First strip spaces and upper-case the text. Then, after that, run our check. The order of the extras insideAnnotatedis the order they run in.(3)gemeans "greater than or equal",le"less than or equal". Also available:gt,lt,multiple_of.(4)Money must be positive, at most 10 digits, and at most 2 decimal places.
Now Sku, Quantity and Money can be used in every model of the service, and every rule lives in one place. FastAPI also copies these constraints into the API documentation automatically, as section 8 shows.
4. Custom validators
Some rules need code. Pydantic has two decorators, one for single fields and one for the whole model.
@field_validator: one field at a time
python
from pydantic import BaseModel, field_validator
class Price(BaseModel):
amount: int
@field_validator("amount", mode="before") # (1)
@classmethod
def strip_currency(cls, value):
if isinstance(value, str):
return value.replace("₹", "").replace(",", "").strip()
return value
print(Price(amount="₹1,499"))text
amount=1499(1)mode="before"runs on the raw input, before type conversion. Here it cleans"₹1,499"into"1499", which the normalintconversion then accepts.
There are four modes, which control when your function runs relative to Pydantic's own type handling.
beforeruns on the raw input. Use it to clean up or reshape input.after, the default, runs on the already-converted value, so you can rely on its type. Use it for business rules.wrapreceives the raw value and a handler that runs Pydantic's own validation. You decide whether, and when, to call it. Use it for fallbacks.plainreplaces Pydantic's own validation completely.
AfterValidator and BeforeValidator inside Annotated are the same idea, attached to a reusable type instead of one model.
@model_validator: rules across fields
Some rules involve several fields. "Each product may appear only once in an order" depends on all the lines together.
python
from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator, model_validator
from pydantic.alias_generators import to_camel
class CreateOrder(BaseModel):
model_config = ConfigDict(extra="forbid", alias_generator=to_camel,
populate_by_name=True) # (1)
customer_email: EmailStr # (2)
lines: list[OrderLine] = Field(min_length=1) # (3)
coupon_code: str | None = None
@field_validator("coupon_code")
@classmethod
def normalise_coupon(cls, value: str | None) -> str | None:
if value is None:
return None
value = value.strip().upper()
if not value.isalnum():
raise ValueError("coupon codes are letters and digits only")
return value
@model_validator(mode="after") # (4)
def no_duplicate_skus(self):
skus = [line.sku for line in self.lines]
if len(skus) != len(set(skus)):
raise ValueError("each product may appear only once")
return self(1)Three settings.extra="forbid"rejects any field the model does not declare, which stops the "sneak in adiscountfield" trick from the opening.alias_generator=to_camelmakes the model accept and producecustomerEmailin JSON, the convention of JavaScript clients, while Python code usescustomer_email.populate_by_name=Truelets Python code use either name.(2)EmailStris a ready-made type that validates email addresses. It needs the optionalemail-validatorpackage, installed withpip install "pydantic[email]".(3)Nested models are validated recursively. Every line is a fullOrderLine.min_length=1rejects an empty order.(4)Anaftermodel validator runs once every field has been validated, so it can trustself.lines. It must returnself.
Now feed it bad input, the way a careless client would.
python
from pydantic import ValidationError
bad = {
"customerEmail": "not-an-email",
"lines": [{"sku": "m", "quantity": 0, "unit_price": "-5"},
{"sku": "m", "quantity": 1, "unit_price": "1.234"}],
"coupon": "x",
}
try:
CreateOrder.model_validate(bad) # (1)
except ValidationError as error:
for problem in error.errors(): # (2)
print(".".join(map(str, problem["loc"])), "|", problem["type"])text
customerEmail | value_error
lines.0.sku | value_error
lines.0.quantity | greater_than_equal
lines.0.unit_price | greater_than
lines.1.sku | value_error
lines.1.unit_price | decimal_max_places
coupon | extra_forbidden(1)model_validatevalidates a dict.model_validate_jsonvalidates a raw JSON string or bytes directly, which is faster because the Rust core parses and validates in one pass.(2)Pydantic does not stop at the first problem. It collects every error, each with alocation path, so a client can highlight every bad field in one round trip. This list is exactly what FastAPI returns in a 422 response.
Notice that the model validator did not run here. It runs only when every field passed, which is why it can trust them. With valid fields but a duplicated product, it reports its own error.
5. Serialisation: from objects back to JSON
Validation turns untrusted input into trusted objects. Serialisation goes the other way, turning objects into dicts or JSON for a response.
python
raw = {"customerEmail": "asha@example.com", "couponCode": " save10 ",
"lines": [{"sku": " mug-blue ", "quantity": 2, "unit_price": "450.00"}]}
order = CreateOrder.model_validate(raw)
print(order.model_dump()) # (1)
print(order.model_dump(mode="json", by_alias=True, exclude_none=True)) # (2)
print(order.model_dump_json(include={"customer_email"})) # (3)text
{'customer_email': 'asha@example.com', 'lines': [{'sku': 'MUG-BLUE', 'quantity': 2, 'unit_price': Decimal('450.00')}], 'coupon_code': 'SAVE10'}
{'customerEmail': 'asha@example.com', 'lines': [{'sku': 'MUG-BLUE', 'quantity': 2, 'unit_price': '450.00'}], 'couponCode': 'SAVE10'}
{"customer_email":"asha@example.com"}(1)model_dumpgives a dict of Python objects. TheDecimalstays aDecimal.(2)mode="json"converts everything to JSON-safe types, so theDecimalbecomes the string"450.00"and money is never rounded through a float.by_alias=Trueuses the camelCase names.exclude_none=Truedrops empty optional fields.(3)model_dump_jsongoes straight to a JSON string, in Rust.includeandexcludepick fields.
Computed fields
A value derived from other fields can be included in the output with @computed_field.
python
from decimal import Decimal
from pydantic import BaseModel, computed_field
class PricedLine(BaseModel):
quantity: int
unit_price: Decimal
@computed_field # (1)
@property
def line_total(self) -> Decimal:
return self.quantity * self.unit_price
print(PricedLine(quantity=2, unit_price="450.00").model_dump())text
{'quantity': 2, 'unit_price': Decimal('450.00'), 'line_total': Decimal('900.00')}(1)A normal@property(3.13.6) is not part of the output. Adding@computed_fieldputs it there, and into the JSON Schema.
6. Unions and the discriminator
A payment can be by card or by UPI, and each has different fields. A plain Card | Upi union makes Pydantic try each model in turn, which is slow and produces confusing errors from every failed attempt. If each model has a fixed tag field, tell Pydantic to use it. That is a discriminated union, the same idea as in TypeScript (3.7.3).
python
from decimal import Decimal
from typing import Annotated, Literal
from pydantic import BaseModel, Field, ValidationError
class Card(BaseModel):
method: Literal["card"] # (1)
last4: str
class Upi(BaseModel):
method: Literal["upi"]
vpa: str
class Payment(BaseModel):
amount: Decimal
details: Annotated[Card | Upi, Field(discriminator="method")] # (2)
payment = Payment.model_validate(
{"amount": "10", "details": {"method": "upi", "vpa": "asha@okbank"}})
print(type(payment.details).__name__, payment.details)
try:
Payment.model_validate({"amount": "10", "details": {"method": "cash"}})
except ValidationError as error:
print(error.errors()[0]["msg"])text
Upi method='upi' vpa='asha@okbank'
Input tag 'cash' found using 'method' does not match any of the expected tags: 'card', 'upi'(1)Each variant has aLiteraltag.(2)Pydantic reads themethodfield first and validates against exactly one model. The result is a realUpiobject, somatch(3.13.16) orisinstancework on it.
7. Everyday tools
Defaults. Unlike a dataclass, Pydantic copies a mutable default such as [] for each instance, so the shared-default bug from 3.13.4 cannot happen. For values computed at creation time, such as timestamps, use Field(default_factory=...).
Immutability. ConfigDict(frozen=True) makes instances read-only and hashable, like a frozen dataclass.
Copies. order.model_copy(update={"coupon_code": "NEW"}) returns a copy with changes. Note that it does not re-validate the update.
Reading from objects. ConfigDict(from_attributes=True) lets model_validate read attributes from any object, not just dicts. That is how you turn a database row object into a response model (3.14.6). Only the declared fields are read, so a password_hash attribute on the row never reaches the response.
Skipping validation. Model.model_construct(...) creates an instance without validating anything. Use it only for data you created yourself and already trust, because it will happily store a quantity of −5.
Validating things that are not models. TypeAdapter validates and serialises any type, such as a list[OrderLine] at the top level of a JSON body.
python
from pydantic import TypeAdapter
lines_adapter = TypeAdapter(list[PricedLine])
lines = lines_adapter.validate_json('[{"quantity": 5, "unit_price": "40"}]')
print(lines, lines_adapter.dump_json(lines))text
[PricedLine(quantity=5, unit_price=Decimal('40'), line_total=Decimal('200'))] b'[{"quantity":5,"unit_price":"40","line_total":"200"}]'8. JSON Schema: the contract other teams read
Every model can describe itself as a JSON Schema, a standard JSON format for describing the shape of JSON data. FastAPI collects these schemas into the OpenAPI document behind its /docs page, so client teams can see every field, type and constraint, and can even generate client code from it.
python
import json
print(json.dumps(OrderLine.model_json_schema()["properties"]["quantity"]))text
{"maximum": 100, "minimum": 1, "title": "Quantity", "type": "integer"}The ge=1, le=100 constraint you wrote once is now enforced at run time and published in the documentation. They cannot drift apart, because they come from the same line.
9. Settings from environment variables
Configuration is input too, and wrong configuration should fail at start-up, not at 2 a.m. The companion package pydantic-settings gives you BaseSettings, a model that reads its fields from environment variables and .env files.
python
import os
from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_prefix="SHOP_", env_file=".env") # (1)
database_url: str # (2)
payment_api_key: SecretStr # (3)
request_timeout_seconds: float = 5.0
debug: bool = False
os.environ.update({"SHOP_DATABASE_URL": "postgresql://db/shop",
"SHOP_PAYMENT_API_KEY": "sk_live_123", "SHOP_DEBUG": "true"})
settings = Settings()
print(settings) # (4)
print(settings.debug, settings.payment_api_key.get_secret_value())text
database_url='postgresql://db/shop' payment_api_key=SecretStr('**********') request_timeout_seconds=5.0 debug=True
True sk_live_123(1)Fields are read from variables namedSHOP_plus the field name, and from a.envfile if one exists.(2)A required field. IfSHOP_DATABASE_URLis missing, creatingSettings()raises aValidationErrornaming it, so the service refuses to start instead of failing on the first database call.(3)SecretStrhides its value inrepr, logs and tracebacks. You must ask for it explicitly withget_secret_value().(4)The text"true"was converted to the booleanTrue, and the key is masked.
One caution that catches real teams. A ValidationError message includes a short preview of the input that failed. For a settings object, that input can include other secrets. Log validation errors from configuration carefully, and never send them to a client.
10. What happens inside Pydantic
Here is the sequence, which also explains why Pydantic is fast.
- At class creation.
BaseModeluses a metaclass (3.13.7). When yourclass OrderLine(BaseModel)statement finishes, the metaclass reads the class's annotations with the run-time typing tools from 3.13.12, including everyAnnotatedextra and every decorated validator. - Build a core schema. It turns all of that into a core schema: a nested dict describing every field, type, constraint and validator.
- Compile it in Rust. It hands the core schema to pydantic-core, which builds a
SchemaValidator, a tree of compiled Rust validator objects, and stores it on the class. - At every validation. Creating a model, or calling
model_validate_json, runs that compiled tree. It only calls back into Python for your own validator functions.
python
print(type(OrderLine.__pydantic_validator__).__name__)
print(list(OrderLine.__pydantic_core_schema__["schema"]["fields"]))text
SchemaValidator
['sku', 'quantity', 'unit_price']So the expensive work, reading hints and planning the checks, happens once per class, at import time. Each request only runs the compiled plan. On a laptop, validating a small model takes about one microsecond, and validating it straight from JSON bytes is barely slower, because parsing and validating happen together in Rust. It is the same "do the analysis once, run the plan many times" idea that FastAPI applies to whole endpoints.
What the interviewer will push on
"What is the difference between validation and coercion in Pydantic?" Validation rejects data that does not fit. Coercion converts data that safely can, such as "2" to 2. Lax mode coerces when no information is lost, so it rejects 2.5 for an int. Strict mode disables coercion. The tell is knowing why lax is the default for web input: everything from forms and query strings arrives as text.
"field_validator modes: before, after, wrap, plain?" Before runs on raw input, after runs on the converted value, wrap gets a handler so you control whether Pydantic's own validation runs, and plain replaces it. Give a use for each. Most business rules are after.
"How do you validate a rule that involves several fields?" @model_validator(mode="after"), which runs only when every field is valid, and must return self.
"Why is Pydantic v2 so much faster than v1?" The validation engine was rewritten in Rust as pydantic-core. Each model's schema is compiled once at class creation, and validating JSON parses and validates in one pass. Mention that your own Python validators still run in Python.
"How do you stop clients from setting fields they should not?" extra="forbid" rejects unknown fields. Use separate input and output models, so a client can never set id, status or is_admin. A response model filters what leaves the server (3.14.3).
Something to volunteer that nobody asks for: ValidationError messages include a preview of the bad input, and model_copy(update=...) and model_construct skip validation entirely. Treat validation errors as potentially sensitive, and never build a model from untrusted data with either of those two methods.
Recall
- Pydantic (Samuel Colvin, 2017; v2 in Rust, 2023) uses type hints to validate and coerce data. Lax mode converts when no information is lost.
strict=Truedisables conversion. - Reusable constrained types:
Annotated[int, Field(ge=1, le=100)],StringConstraints(strip_whitespace=True, to_upper=True),AfterValidator(func). @field_validatorwith modesbefore,after,wrapandplain.@model_validator(mode="after")for cross-field rules. Errors are collected, each with aloc.model_config:extra="forbid",alias_generator=to_camel,populate_by_name,frozen,from_attributes,strict.- Serialisation:
model_dump(mode="json", by_alias=True, exclude_none=True),model_dump_json,include/exclude, and@computed_field. - A discriminated union uses a
Literaltag andField(discriminator=...).TypeAdapterhandles non-model types.model_json_schema()produces the JSON Schema used in FastAPI docs. BaseSettingsreads environment variables, andSecretStrhides secrets.model_constructandmodel_copy(update=...)skip validation.- Inside: a metaclass builds a core schema once per class, and pydantic-core compiles it into a Rust
SchemaValidator.
Self-test: Why is 2.0 accepted for an int field but 2.5 rejected? In which mode would you strip a ₹ sign, and why? Why does a model validator not run when a field is invalid? What does extra="forbid" protect against? Where does the expensive work in Pydantic happen, at import or per request?
Quiz Bank
FoundationalWhat is the difference between a dataclass and a Pydantic model?
Both declare fields with type hints and generate an __init__. A dataclass trusts its input: it stores whatever it is given, with no checking or conversion. A Pydantic model validates every field against its type and constraints when it is created, converts compatible input such as "2" into 2, collects all errors into one ValidationError, and can serialise itself to JSON and describe itself as a JSON Schema. Pydantic costs about a microsecond per small object, so use it at trust boundaries such as API requests and configuration, and dataclasses for internal data you already trust.
AppliedYour API returns Decimal prices, and a client reports 19.990000000000002 in some responses. Where is the bug and how do you fix it?
Somewhere a Decimal was converted to a float before being serialised, for example by a hand-written float(price), a json.dumps with a float-based default, or a response model that declares the field as float. Binary floats cannot represent most decimal fractions exactly. Keep the field typed as Decimal in both the database model and the Pydantic response model, and let Pydantic serialise it with mode="json", which writes it as an exact string such as "19.99". If clients need a number, agree on integer minor units such as paise, rather than floats.
InterviewDesign request models for creating and updating a product so that clients cannot set the ID, the creation date or the stock level directly.
Use separate models instead of one shared class. ProductCreate has only client-settable fields, such as name, description, price and category, each with constraints, and extra="forbid". ProductUpdate has the same fields, all optional with default None, and the endpoint applies only the fields the client actually sent, using model_dump(exclude_unset=True). ProductOut is the response model, with id, created_at and stock included and from_attributes=True so it can be built from a database row. The server sets id and created_at. Stock changes only through dedicated inventory endpoints. With extra="forbid", a client that sends "stock": 999 gets a 422 instead of being silently ignored.
StaffValidation is showing up as 30% of CPU time in a high-traffic FastAPI service. How would you investigate and reduce it?
Profile first to see which models and which validators are hot. Common causes are large nested payloads validated more than once, for example the request body validated, converted to a dict, and validated again into another model, or response models re-validating data that came from trusted internal objects. Others are custom Python validators running per item on long lists, which leave the fast Rust path, and plain unions without a discriminator, which try every variant. Fixes: validate JSON bytes directly with model_validate_json, add discriminators, move simple checks from Python validators to declarative constraints that run in Rust, avoid double conversions, and, for trusted internal data headed to a response, serialise directly or use model_construct deliberately. If payloads are huge, consider streaming or paginating instead of validating one giant document.
Next: you have seen how Pydantic turns raw data into trusted objects. 3.14.3 shows how FastAPI decides, from your function's signature alone, which data comes from the URL, which from the query string and which from the body, and why def and async def endpoints run in completely different places.