skip to content

Strict vs Lax Coercion

Pydantic turns '5' into 5 unless strict mode says otherwise. Interviewers ask which conversions lax mode allows, how a union picks its member, and why a discriminated union is the reliable choice.

on this pageshow

explore

questions

6

In Pydantic 2's default lax mode, which conversions does it apply to int, bool and str fields, and which inputs does it refuse?

level: middleimportance: must knowfreq 66%

answer

  1. a published table, not a free-for-all
  2. whole floats pass, fractions fail
  3. a fixed word list for booleans
  4. numbers are no longer strings

basics

~20 s

Pydantic 2's lax mode turns digit strings and whole-valued floats into int and a fixed word list ('true', 'yes', 'on', '1' and opposites) into bool, but rejects fractional floats for int and, since version 2, numbers for str.

solid answer

~40 s

Pydantic 2 validates in lax mode by default, and a published conversion table decides what each type accepts. An `int` field takes `'1250'` and `12.0` but rejects `12.5` with `int_from_float` and `'12x'` with `int_parsing`; it never truncates or rounds. A `bool` field takes `0`, `1` and, case-insensitively, `'0'`, `'off'`, `'f'`, `'false'`, `'n'`, `'no'` or `'1'`, `'on'`, `'t'`, `'true'`, `'y'`, `'yes'`; anything else, such as `'maybe'`, fails with `bool_parsing`. A `str` field takes strings, UTF-8 bytes and enum values, but an `int`, `float` or `Decimal` fails with `string_type`: version 1 turned `42` into `'42'`, and version 2 only does so when `coerce_numbers_to_str=True` is set in `ConfigDict`. Lax mode is a short list of unambiguous conversions, not whatever Python could cast.

code

python · 17 lines
python
from pydantic import BaseModel, ValidationError


class PaymentEvent(BaseModel):
    amount_cents: int
    captured: bool
    reference: str


print(PaymentEvent(amount_cents='1250', captured='yes', reference='ab-1'))
#> amount_cents=1250 captured=True reference='ab-1'

try:
    PaymentEvent(amount_cents=12.5, captured='maybe', reference=1001)
except ValidationError as exc:
    print([e['type'] for e in exc.errors()])
    #> ['int_from_float', 'bool_parsing', 'string_type']

go deeper

for a junior

Recall that Pydantic converts '1250' to 1250 by default and that a bad value raises ValidationError with a type per field.

for a middle

Walk through the int, bool and str rows: whole floats pass, fractions fail with int_from_float, the boolean word list, and numbers refused for str.

for a senior

Show you read error types to spot producer bugs, and know which lax conversions, such as True to 1, deserve a strict field in a payment feed.

for a principal

Frame lax mode as a contract decision: which conversions your services tolerate silently, and where a refusal should surface a producer's mistake instead.

## What "lax" means in Pydantic 2 Pydantic 2 validates every field in **lax mode** unless strict mode is switched on. Lax does not mean "anything goes". Each target type has a fixed list of input types it accepts, published as the **conversion table** in the Pydantic documentation, and many entries carry a condition. The guiding idea is that a conversion must be unambiguous: `'1250'` is clearly the integer 1250, while `12.5` is not an integer at all. Lax mode exists because real input often arrives as text or as a looser type than the model declares. A payment-events feed may send `"amount_cents": "1250"` from one producer and `1250` from another, a capture flag as `"yes"`, a settlement date as `"2026-10-01"`. Lax mode accepts both shapes and hands your code one Python type. ## Integers An `int` field accepts: - an `int`, as is; - a string or bytes made only of digits, such as `'1250'`; `'12x'` fails with **`int_parsing`**; - a `float` whose fractional part is zero, so `12.0` becomes `12`; `12.5` fails with **`int_from_float`**, and NaN or infinity fail too; - a finite `Decimal` with no fractional part (Python input only); - a `bool`, so `True` becomes `1`: the table lists it for lax mode, and strict mode explicitly forbids it. The fractional-float rule is the one candidates get wrong: Pydantic never truncates or rounds. A producer that sends cents as `1250.0` passes; one that sends `12.50` dollars into a cents field fails loudly, which is exactly what you want. ## Booleans A `bool` field accepts `True` and `False`, the integers `0` and `1` (any other integer fails), and a string that, lowercased, is one of these: | Becomes `False` | Becomes `True` | |---|---| | `'0'`, `'off'`, `'f'`, `'false'`, `'n'`, `'no'` | `'1'`, `'on'`, `'t'`, `'true'`, `'y'`, `'yes'` | Any other string, such as `'maybe'` or `'enabled'`, fails with **`bool_parsing`**. This is the opposite of Python truthiness, where every non-empty string is true: in Pydantic, `'false'` really becomes `False`. ## Strings A `str` field accepts strings, `bytes` and `bytearray` decoded as UTF-8 (Python input only), and enum members by their value. It does **not** accept numbers: `42` fails with **`string_type`**. Version 1 converted numbers to strings silently; version 2 made that opt-in through `coerce_numbers_to_str=True` in `ConfigDict`, which turns `int`, `float` and `Decimal` inputs into strings in lax mode. A `reference: str` field that receives `1001` from a careless producer therefore fails on version 2 where it passed on version 1. ## Other types worth knowing | Field type | Lax mode also accepts | Condition | |---|---|---| | `float` | `int`, `bool`, numeric strings | the string must look like a number | | `Decimal` | `int`, `float`, numeric strings | the string must look like a number | | `date` | `'YYYY-MM-DD'` strings, Unix timestamps | a timestamp must land exactly on a date | | `UUID` | strings | must parse as a UUID | | `tuple` | `list`, `set`, `frozenset`, `deque` | Python input; from JSON, an array | Python input and JSON input do not have identical rows: bytes, sets and `Decimal` instances can only arrive from Python, so their rows are Python-only. ## How strict mode changes these rows Strict mode keeps only the "Strict" column of the same table. For the three types above that means: - `int` accepts only `int`, and `bool` is explicitly forbidden, so `'1250'`, `12.0` and `True` all fail; - `bool` accepts only `True` and `False`, so `'yes'` and `1` fail; - `str` accepts only `str`, so UTF-8 bytes fail too. Strict mode can be switched on for a model, a field or a single call, and JSON input relaxes it for types JSON cannot express, such as dates; those details belong to the questions on strict mode itself. ## Reading the failures When a value cannot be converted, the `ValidationError` holds one entry per failing field, each with a `type`, a `loc` and the rejected `input`. Three habits help: 1. Read the `type` first. A `*_parsing` type means the input was text that could not be parsed; a `*_type` type means the input's type is not accepted for that field in the current mode. 2. Treat `int_from_float` as a contract question (cents or dollars?) rather than something to coerce around. 3. Decide per field whether lax acceptance is a convenience or a hidden producer bug. Where it is a bug, strict mode on that field is the switch. Knowing the table well enough to predict these outcomes is what separates "Pydantic converts stuff" from an answer an interviewer trusts.

  • How do you make a str field accept numbers again in Pydantic 2?
    Set `coerce_numbers_to_str=True` in the model's `ConfigDict`. In lax mode it then converts `int`, `float` and `Decimal` inputs to their string form, so `42` becomes `'42'`. It is off by default because version 2 stopped doing this silently; enabling it per model keeps the conversion visible in code.
  • Does an int field in Pydantic 2 accept True?
    In lax mode, yes: the conversion table lists `bool` as an accepted input for `int`, so `True` becomes `1` and `False` becomes `0`. In strict mode `bool` is explicitly forbidden for `int` and validation fails. If a feed can confuse flags with counts, a strict count field is the guard.

  • Lax mode converts any value that Python's int() or str() would accept.
  • A str field turns the number 42 into '42' by default in Pydantic 2.
  • Any non-empty string, including 'false', becomes True for a bool field.
  • An int field silently truncates 12.5 to 12.
  • An int field rejects True and False even in lax mode.

Assumes Pydantic 2; version 1 coerced numbers to str silently, version 2 needs coerce_numbers_to_str=True.

open as a page

In Pydantic 2, how do you turn on strict mode for a whole model, for one field, or for a single validation call?

level: middleimportance: should knowfreq 50%

basics

~10 s

Pydantic 2 offers three scopes: ConfigDict(strict=True) for a model, Field(strict=True) or StrictInt-style types for one field, and strict=True on model_validate or a TypeAdapter method for one call.

open as a page

In Pydantic 2, why would you validate three payment event kinds as a discriminated union on a Literal tag rather than a plain union?

level: seniorimportance: should knowfreq 42%

basics

~10 s

A Pydantic 2 discriminated union reads one tag field, typed as a Literal on each member, and validates only the member it names, so selection is predictable, faster, and errors describe just that member.

open as a page

Why can one strict Pydantic 2 model accept a payload through model_validate_json yet reject the same data passed to model_validate as a dict?

level: seniorimportance: should knowfreq 30%

basics

~10 s

Pydantic 2 validates JSON and Python input under different rules: in JSON mode, strict still accepts strings for dates, UUIDs and Decimals, because JSON has no such types, while Python mode demands real instances.

open as a page

In Pydantic 2, how does the default smart union mode choose a member, and when would you set union_mode='left_to_right' instead?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Smart mode, the Pydantic 2 default, picks the best match: for plain types an exact match first, then the leftmost strict, then the leftmost lax match. left_to_right takes the first member that validates, so order decides.

open as a page

Would you make Pydantic 2's strict mode the team default for inbound models, and what would that policy cost your services?

level: principalimportance: should knowfreq 24%

basics

~20 s

Pydantic 2's strict mode suits JSON contracts between services you own, validated with model_validate_json; text-native inputs usually need lax mode. Most teams land on strict risky fields plus a strict base model, rolled out after measuring rejections.

open as a page