Why does a Pydantic 2 generic `Page[T]` model return plain dicts or lose fields when built unparametrized, and what fixes it?
answer
- unparametrized type variable
- falls back to its bound
- otherwise Any
- parametrize at the call site
basics
~10 sAn unparametrized Pydantic 2 generic validates its type variable as its bound, constraints or default, and otherwise as Any. So items stay raw dicts, or shrink to the bound's fields. Validate with Page[LineItem] instead.
solid answer
~40 sA generic model is declared as `class Page(BaseModel, Generic[T])` (or `class Page[T](BaseModel)`, fully supported since 2.11). Writing `Page[LineItem]` makes Pydantic create and cache a subclass whose `items` are validated as `LineItem`. Used **unparametrized**, Pydantic treats the type variable like a bare `list` element: it validates against the variable's **bound** or **constraints** if it has them, then its **default**, and otherwise against **`Any`**. With an unbound `T`, `Page(items=[...])` keeps the partner's dicts unvalidated. With `bound=ItemBase`, items are validated as `ItemBase` and a subclass's extra fields are lost. Always parametrize at the call site. Pydantic also does not check that a parametrization respects the bound.
code
python · 22 linesfrom typing import Generic, TypeVar
from pydantic import BaseModel
T = TypeVar('T')
class LineItem(BaseModel):
sku: str
quantity: int
class Page(BaseModel, Generic[T]):
items: list[T]
next_cursor: str | None = None
raw = {'items': [{'sku': 'S1', 'quantity': '3'}]}
print(Page.model_validate(raw).items)
#> [{'sku': 'S1', 'quantity': '3'}]
print(Page[LineItem].model_validate(raw).items)
#> [LineItem(sku='S1', quantity=3)]go deeper
Recall how to declare a generic model with BaseModel and Generic, and that Page[LineItem] validates each item as a LineItem.
Explain that parametrizing creates a cached subclass, and the fallback order for an unparametrized type variable: bound or constraints, then default, then Any.
Diagnose silent data loss from validating against a bound model, fix it by parametrizing or naming subclasses, and add a test that asserts the element type.
Decide whether shared envelope models like Page are generic or concrete per resource, weighing reuse against the risk of unparametrized use.
## Generic models in Pydantic 2 A **generic model** is a model with one or more **type variables** that are filled in later. For paginated partner responses, one `Page` model can carry orders, line items or customers: ```python from typing import Generic, TypeVar from pydantic import BaseModel T = TypeVar('T') class Page(BaseModel, Generic[T]): items: list[T] next_cursor: str | None = None ``` The base classes go in that order: `BaseModel`, then `Generic`. On Python 3.12 and later the new syntax `class Page[T](BaseModel)` works as well, with full support (including type variable defaults) since version 2.11. Version 1 needed a separate `GenericModel` base class from `pydantic.generics`; version 2 removed it. ## What parametrizing does `Page[LineItem]` is not just a type hint. Pydantic **creates a subclass at runtime** with `T` replaced by `LineItem`, builds its schema and **caches** it, so repeated parametrizations cost little. Validating through that subclass converts every element of `items` into a `LineItem`, with all of `LineItem`'s checks. Configuration, validators and serializers declared on the generic model are applied to each parametrized class, as with ordinary inheritance. A parametrized generic can also be used as a field type: `latest: Page[Order]`. ## The unparametrized trap If code validates through the bare class, `Page(items=...)` or `Page.model_validate(raw)`, there is no concrete type to substitute. Pydantic then follows the same rules it uses for a bare `list` or `dict`: 1. If the type variable has a **bound** or **constraints**, that type is used. 2. Otherwise, if it has a **default** (the newer type-parameter defaults), the default is used. 3. Otherwise, Pydantic falls back to **`Any`**. The consequences differ by case: | Type variable | Unparametrized `Page.model_validate(raw)` gives | |---|---| | `T = TypeVar('T')` | items left as the incoming dicts, **unvalidated** | | `T = TypeVar('T', bound=ItemBase)` | items validated as `ItemBase`; fields only a subclass declares are **dropped** | | `T = TypeVar('T', default=LineItem)` | items validated as `LineItem` | The bound case is the nasty one. The documentation's example has an `ItemHolder` whose type variable is bound to an empty `ItemBase`: validating `{'item': {'value': 1}}` unparametrized produces `ItemBase()`, and the `value` is gone without any error. Serialization adds its own twist: a value validated against a bound model is treated as `Any` when dumping. ## The fix - **Parametrize at the point of validation**: `Page[LineItem].model_validate(raw)`. - For a shape used everywhere, define a named subclass, `class LineItemPage(Page[LineItem]): pass`, which reads well in error messages and works in `isinstance` checks. The documentation advises against `isinstance(x, Page[LineItem])` with a parametrized generic; checking against the plain `Page` or a named subclass is fine. - Give the type variable a **default** if a sensible fallback exists, so forgetting to parametrize degrades gracefully. - Add a test that validates a real partner page and asserts the element type. ## Naming and caching of parametrized classes Each parametrization is a real class, and its default name is built from the generic name and its arguments, such as `Page[LineItem]`. That name appears in error titles (`1 validation error for Page[LineItem]`) and in JSON Schema. Two tools help here: - Override the class method `model_parametrized_name()` to produce names such as `LineItemPage` across every parametrization at once. - Prefer a named subclass when one parametrization is used all over the codebase; its own name is then used. Because parametrized classes are cached, writing `Page[LineItem]` in many places does not build many schemas, so the explicit form costs nothing worth avoiding. ## Two more behaviours to know - **Pydantic does not check the bound when you parametrize.** `Page[str]` is accepted even if `T` is bound to a model type; a static type checker may complain, Pydantic will not. - **Nested generics may revalidate.** When a field is typed `Page[Any]` and receives a `Page[LineItem]` instance, Pydantic recognises a loosely compatible generic and revalidates its contents, which runs custom validators a second time. That is surprising if a validator has side effects. ## Where the line sits How type variables, bounds and `Generic` work as Python typing is a language subject. The Pydantic question is what validation does with them: parametrized classes validate the concrete type, and unparametrized ones fall back to the bound, the constraints, the default, or `Any`.
- In Pydantic 2, does `Page[str]` fail when T is declared as `TypeVar('T', bound=ItemBase)`?No. Pydantic does not check that the type you parametrize with is assignable to the type variable's bound; it builds `Page[str]` and validates items as strings. A static type checker may flag it, but at runtime the bound only matters when the model is used unparametrized.
- In Pydantic 2, why define `class LineItemPage(Page[LineItem]): pass` instead of writing `Page[LineItem]` everywhere?A named subclass gives one place to change the element type, a readable class name in errors and schemas, and a safe target for `isinstance`, which the documentation advises against using with a parametrized generic like `Page[LineItem]`.
- An unparametrized generic model infers the element type from the data.
- An unparametrized type variable always raises a validation error.
- Pydantic rejects a parametrization that breaks the type variable's bound.
- Pydantic 2 generic models must inherit from GenericModel.
- A bound type variable keeps a subclass's extra fields when unparametrized.