Clarify Union documentation for response_model in python 3.10+ #16169

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class BaseItem(BaseModel):
    description: str
    type: str


class CarItem(BaseItem):
    type: str = "car"


class PlaneItem(BaseItem):
    type: str = "plane"
    size: int


items = {
    "item1": {"description": "All my friends drive a low rider", "type": "car"},
    "item2": {
        "description": "Music is my aeroplane, it's my aeroplane",
        "type": "plane",
        "size": 5,
    },
}


@app.get("/items/{item_id}", response_model=PlaneItem | CarItem)
async def read_item(item_id: str):
    return items[item_id]

Description

I noticed a possible contradiction in the FastAPI documentation regarding Union and the use of the | operator with response_model.

In the Python 3.10+ example in the "Union or anyOf" section, the documentation uses:

@app.get(
    "/items/{item_id}",
    response_model=PlaneItem | CarItem,
)
async def read_item(item_id: str):
    return items[item_id]

However, immediately below, in the "Union in Python 3.10" section, the documentation says:

Because we are passing it as a value to an argument instead of putting it in a type annotation, we have to use Union even in Python 3.10.

It then states that using:

response_model=PlaneItem | CarItem

would result in an error because Python would try to perform an invalid operation between PlaneItem and CarItem instead of interpreting it as a type annotation.

This seems contradictory because the Python 3.10+ example immediately above uses exactly PlaneItem | CarItem as the value of response_model.

I tested the example with a current Python/FastAPI setup, and:

response_model=PlaneItem | CarItem

works as expected.

My understanding is that in Python 3.10+, PlaneItem | CarItem produces a union type at runtime, so it can be passed as the value of response_model. The fact that response_model is a runtime argument rather than a type annotation does not, by itself, mean that the | syntax cannot be used.

Could someone clarify whether the explanation in the "Union in Python 3.10" section is outdated, or whether there is some version-specific behavior that I am missing?

If the explanation is outdated, I would be happy to submit a documentation PR to clarify the wording and make the two sections consistent.

Relevant documentation

The current Python 3.10+ example uses:

response_model=PlaneItem | CarItem

while the following section says that the same syntax would result in an error and that Union[...] must be used.

I'm opening this discussion first to confirm the intended behaviour and documentation before proposing a PR. I'm happy to contribute a fix if needed

Operating System

macOS

Operating System Details

macOS Tahoe 26.6

FastAPI Version

0.140.0

Pydantic Version

2.13.4

Python Version

3.10.20

Additional Context

No response