Top-level Discriminated Union with callable discriminator not supported? #12941

frankie567 · 2024-11-15T15:05:36Z

frankie567
Nov 15, 2024

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 typing import Annotated, Any, Literal

import httpx
import pytest
from fastapi import FastAPI
from pydantic import BaseModel, Discriminator, Tag

# Discriminated union with a callable discriminator


class Pie(BaseModel):
    time_to_cook: int
    num_ingredients: int


class ApplePie(Pie):
    fruit: Literal["apple"] = "apple"


class PumpkinPie(Pie):
    filling: Literal["pumpkin"] = "pumpkin"


def get_discriminator_value(v: Any) -> str:
    if isinstance(v, dict):
        return v.get("fruit", v.get("filling"))
    return getattr(v, "fruit", getattr(v, "filling", None))


Dessert = Annotated[
    Annotated[ApplePie, Tag("apple")] | Annotated[PumpkinPie, Tag("pumpkin")],
    Discriminator(get_discriminator_value),
]


# FastAPI app

app = FastAPI()


@app.post("/dessert")
async def dinner(dessert: Dessert) -> dict[str, Any]:
    return dessert.model_dump()


# Tests


@pytest.mark.asyncio
async def test_dessert() -> None:
    async with httpx.AsyncClient(
        transport=httpx.ASGITransport(app=app), base_url="http://app.local"
    ) as client:
        response = await client.post(
            "/dessert",
            json={"time_to_cook": 42, "num_ingredients": 8, "fruit": "apple"},
        )
    assert response.status_code == 200
    assert response.json() == {
        "time_to_cook": 42,
        "num_ingredients": 8,
        "fruit": "apple",
    }
    async with httpx.AsyncClient(app=app, base_url="http://test") as client:
        response = await client.post(
            "/dessert",
            json={"time_to_cook": 42, "num_ingredients": 8, "filling": "pumpkin"},
        )
    assert response.status_code == 200
    assert response.json() == {
        "time_to_cook": 42,
        "num_ingredients": 8,
        "filling": "pumpkin",
    }

Description

I'm implementing an endpoint with a payload schema defined as a Discriminated Union with a Callable Discriminator.

In this case, FastAPI seems unable to correctly validate it, and return a 422 error which is a bit off-topic:

{
    "detail": [
        {
            "input": null,
            "loc": [
                "query",
                "dessert"
            ],
            "msg": "Field required",
            "type": "missing"
        }
    ]
}

It seems FastAPI incorrectly identifies the field as a query field instead of a body field.

Operating System

macOS

Operating System Details

Sequoia 15.1 - Apple Silicon

FastAPI Version

0.115.5

Pydantic Version

2.9.2

Python Version

3.12.7

Additional Context

Solution 1 (not working)

Adding Body(...) as a default argument to the parameter makes it seem to work:

@app.post("/dessert")
async def dinner(dessert: Dessert = Body(...)) -> dict[str, Any]:
    return dessert.model_dump()

But actually, the discriminator is not called at all in this case.

Full code

from typing import Annotated, Any, Literal

import httpx
import pytest
from fastapi import Body, FastAPI
from pydantic import BaseModel, Discriminator, Tag

# Discriminated union with a callable discriminator


class Pie(BaseModel):
    time_to_cook: int
    num_ingredients: int


class ApplePie(Pie):
    fruit: Literal["apple"] = "apple"


class PumpkinPie(Pie):
    filling: Literal["pumpkin"] = "pumpkin"


def get_discriminator_value(v: Any) -> str:
    assert False, "This should not be called"


Dessert = Annotated[
    Annotated[ApplePie, Tag("apple")] | Annotated[PumpkinPie, Tag("pumpkin")],
    Discriminator(get_discriminator_value),
]


# FastAPI app

app = FastAPI()


@app.post("/dessert")
async def dinner(dessert: Dessert = Body(...)) -> dict[str, Any]:
    return dessert.model_dump()


# Tests


@pytest.mark.asyncio
async def test_dessert() -> None:
    async with httpx.AsyncClient(
        transport=httpx.ASGITransport(app=app), base_url="http://app.local"
    ) as client:
        response = await client.post(
            "/dessert",
            json={"time_to_cook": 42, "num_ingredients": 8, "fruit": "apple"},
        )
    assert response.status_code == 200
    assert response.json() == {
        "time_to_cook": 42,
        "num_ingredients": 8,
        "fruit": "apple",
    }
    async with httpx.AsyncClient(app=app, base_url="http://test") as client:
        response = await client.post(
            "/dessert",
            json={"time_to_cook": 42, "num_ingredients": 8, "filling": "pumpkin"},
        )
    assert response.status_code == 200
    assert response.json() == {
        "time_to_cook": 42,
        "num_ingredients": 8,
        "filling": "pumpkin",
    }

Solution 2 (working, but type checker unhappy)

Adding Body and repeating the discriminator argument on it makes it work, but mypy is unhappy since Body expects str | None for this parameter`:

@app.post("/dessert")
async def dinner(
    dessert: Dessert = Body(..., discriminator=Discriminator(get_discriminator_value)),
) -> dict[str, Any]:
    return dessert.model_dump()

Full code

from typing import Annotated, Any, Literal

import httpx
import pytest
from fastapi import Body, FastAPI
from pydantic import BaseModel, Discriminator, Tag

# Discriminated union with a callable discriminator


class Pie(BaseModel):
    time_to_cook: int
    num_ingredients: int


class ApplePie(Pie):
    fruit: Literal["apple"] = "apple"


class PumpkinPie(Pie):
    filling: Literal["pumpkin"] = "pumpkin"


def get_discriminator_value(v: Any) -> str:
    if isinstance(v, dict):
        return v.get("fruit", v.get("filling"))
    return getattr(v, "fruit", getattr(v, "filling", None))


Dessert = Annotated[
    Annotated[ApplePie, Tag("apple")] | Annotated[PumpkinPie, Tag("pumpkin")],
    Discriminator(get_discriminator_value),
]


# FastAPI app

app = FastAPI()


@app.post("/dessert")
async def dinner(
    dessert: Dessert = Body(..., discriminator=Discriminator(get_discriminator_value)),
) -> dict[str, Any]:
    return dessert.model_dump()


# Tests


@pytest.mark.asyncio
async def test_dessert() -> None:
    async with httpx.AsyncClient(
        transport=httpx.ASGITransport(app=app), base_url="http://app.local"
    ) as client:
        response = await client.post(
            "/dessert",
            json={"time_to_cook": 42, "num_ingredients": 8, "fruit": "apple"},
        )
    assert response.status_code == 200
    assert response.json() == {
        "time_to_cook": 42,
        "num_ingredients": 8,
        "fruit": "apple",
    }
    async with httpx.AsyncClient(app=app, base_url="http://test") as client:
        response = await client.post(
            "/dessert",
            json={"time_to_cook": 42, "num_ingredients": 8, "filling": "pumpkin"},
        )
    assert response.status_code == 200
    assert response.json() == {
        "time_to_cook": 42,
        "num_ingredients": 8,
        "filling": "pumpkin",
    }

Investigation

My guess is that FastAPI is troubled by the "sub-annotated" model with the Tag construct like Annotated[ApplePie, Tag("apple")], explaining why it sees it as a query parameter by default. Probably something around here:

fastapi/fastapi/dependencies/utils.py

Lines 457 to 460 in 1cfea40

    
           elif not field_annotation_is_scalar(annotation=type_annotation): 
        
               field_info = params.Body(annotation=use_annotation, default=default_value) 
        
           else: 
        
               field_info = params.Query(annotation=use_annotation, default=default_value)

fastapi/fastapi/_compat.py

Lines 562 to 580 in 1cfea40

    
           def _annotation_is_complex(annotation: Union[Type[Any], None]) -> bool: 
        
               return ( 
        
                   lenient_issubclass(annotation, (BaseModel, Mapping, UploadFile)) 
        
                   or _annotation_is_sequence(annotation) 
        
                   or is_dataclass(annotation) 
        
               ) 
        
           def field_annotation_is_complex(annotation: Union[Type[Any], None]) -> bool: 
        
               origin = get_origin(annotation) 
        
               if origin is Union or origin is UnionType: 
        
                   return any(field_annotation_is_complex(arg) for arg in get_args(annotation)) 
        
               return ( 
        
                   _annotation_is_complex(annotation) 
        
                   or _annotation_is_complex(origin) 
        
                   or hasattr(origin, "__pydantic_core_schema__") 
        
                   or hasattr(origin, "__get_pydantic_core_schema__") 
        
               )

frankie567 · 2024-11-15T15:44:25Z

frankie567
Nov 15, 2024
Author

I found a simple fix and took the liberty to open a PR for it: #12942

0 replies

YuriiMotov · 2025-05-21T16:21:01Z

YuriiMotov
May 21, 2025
Collaborator

I think it's too complicated structure for Query parameters. It's better to use Body in this case if it's possible.

@app.post("/dessert")
async def dinner(
    dessert: Annotated[Dessert, Body()],
) -> dict[str, Any]:
    return dessert.model_dump()

Works fine in current versions of FastAPI and Pydantic.
Mypy is happy as well.

Details

from typing import Annotated, Any, Literal

import httpx
import pytest
from fastapi import Body, FastAPI
from pydantic import BaseModel, Discriminator, Tag

# Discriminated union with a callable discriminator


class Pie(BaseModel):
    time_to_cook: int
    num_ingredients: int


class ApplePie(Pie):
    fruit: Literal["apple"] = "apple"


class PumpkinPie(Pie):
    filling: Literal["pumpkin"] = "pumpkin"


def get_discriminator_value(v: Any) -> str | None:
    if isinstance(v, dict):
        return v.get("fruit", v.get("filling"))
    return getattr(v, "fruit", getattr(v, "filling", None))


Dessert = Annotated[
    Annotated[ApplePie, Tag("apple")] | Annotated[PumpkinPie, Tag("pumpkin")],
    Discriminator(get_discriminator_value),
]


# FastAPI app

app = FastAPI()


@app.post("/dessert")
async def dinner(
    dessert: Annotated[Dessert, Body()],
) -> dict[str, Any]:
    return dessert.model_dump()


# Tests


@pytest.mark.asyncio
async def test_dessert() -> None:
    async with httpx.AsyncClient(
        transport=httpx.ASGITransport(app=app), base_url="http://app.local"
    ) as client:
        response = await client.post(
            "/dessert",
            json={"time_to_cook": 42, "num_ingredients": 8, "fruit": "apple"},
        )
    assert response.status_code == 200
    assert response.json() == {
        "time_to_cook": 42,
        "num_ingredients": 8,
        "fruit": "apple",
    }


    async with httpx.AsyncClient(
        transport=httpx.ASGITransport(app=app), base_url="http://app.local"
    ) as client:
        response = await client.post(
            "/dessert",
            json={"time_to_cook": 42, "num_ingredients": 8, "filling": "pumpkin"},
        )
    assert response.status_code == 200
    assert response.json() == {
        "time_to_cook": 42,
        "num_ingredients": 8,
        "filling": "pumpkin",
    }

3 replies

frankie567 May 21, 2025
Author

I think it's too complicated structure for Query parameters. It's better to use Body in this case if it's possible.

I do talk about a Body parameter here.

@app.post("/dessert")
async def dinner(
    dessert: Annotated[Dessert, Body()],
) -> dict[str, Any]:
    return dessert.model_dump()

Yes, that's similar to my Solution 1 — but there were probably updates that now make it work.

However, IMO, it's still a workaround; we shouldn't have to do that. In standard use-case, FastAPI automatically guesses that a Pydantic model is passed as a body, without having to explicitly set it.

I've opened a PR with a fix some time ago to support that: #12942

YuriiMotov May 21, 2025
Collaborator

Agree.
I would recommend you add the description of the problem to PR.
Just pointing to the discussion is not very convenient for reviewers. This discussion is quite verbose and part of it is outdated

frankie567 May 22, 2025
Author

Done 👍 I've also rebased/updated it.

willsawyerrrr · 2025-06-24T17:58:29Z

willsawyerrrr
Jun 24, 2025

I've experienced the same behaviour without using a callable discriminator.

Simply using the union of the different alternatives works as expected - with the parameter in the body.
However, defining the type annotation as a type alias results in the same undesired behaviour - with the parameter in the query.

from typing import Any, Literal

from fastapi import FastAPI
from pydantic import BaseModel

# Discriminated union with implicit discriminator


class Pie(BaseModel):
    time_to_cook: int
    num_ingredients: int


class ApplePie(Pie):
    fruit: Literal["apple"] = "apple"


class PumpkinPie(Pie):
    filling: Literal["pumpkin"] = "pumpkin"


# Select one of the below definitions
type Dessert = ApplePie | PumpkinPie  # Results in `dessert` being a query param
Dessert = ApplePie | PumpkinPie       # Results in `dessert` being a body param (as desired)


# FastAPI app

app = FastAPI()


@app.post("/dessert")
async def dinner(dessert: Dessert) -> dict[str, Any]:
    return dessert.model_dump()

@frankie567, can your fix also handle this case?

1 reply

YuriiMotov Jun 24, 2025
Collaborator

type Dessert = ApplePie | PumpkinPie

FastAPI doesn't support the above syntax yet: #10719
Use Dessert = ApplePie | PumpkinPie for now

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Top-level Discriminated Union with callable discriminator not supported? #12941

Uh oh!

{{title}}

Uh oh!

Replies: 3 comments 4 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Top-level Discriminated Union with callable discriminator not supported? #12941

Uh oh!

frankie567 Nov 15, 2024

First Check

Commit to Help

Example Code

Description

Operating System

Operating System Details

FastAPI Version

Pydantic Version

Python Version

Additional Context

Solution 1 (not working)

Solution 2 (working, but type checker unhappy)

Investigation

Replies: 3 comments · 4 replies

Uh oh!

frankie567 Nov 15, 2024 Author

Uh oh!

YuriiMotov May 21, 2025 Collaborator

Uh oh!

frankie567 May 21, 2025 Author

Uh oh!

YuriiMotov May 21, 2025 Collaborator

Uh oh!

frankie567 May 22, 2025 Author

Uh oh!

willsawyerrrr Jun 24, 2025

Uh oh!

YuriiMotov Jun 24, 2025 Collaborator

frankie567
Nov 15, 2024

Replies: 3 comments 4 replies

frankie567
Nov 15, 2024
Author

YuriiMotov
May 21, 2025
Collaborator

frankie567 May 21, 2025
Author

YuriiMotov May 21, 2025
Collaborator

frankie567 May 22, 2025
Author

willsawyerrrr
Jun 24, 2025

YuriiMotov Jun 24, 2025
Collaborator