API docmentation cannot be built for Pydantic Nested Discriminated Unions

[akalex]

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, Literal, Union
from fastapi import FastAPI

from pydantic import BaseModel, Field


class BlackCat(BaseModel):
    pet_type: Literal['cat']
    color: Literal['black']
    black_name: str


class WhiteCat(BaseModel):
    pet_type: Literal['cat']
    color: Literal['white']
    white_name: str


Cat = Annotated[Union[BlackCat, WhiteCat], Field(discriminator='color')]


class Dog(BaseModel):
    pet_type: Literal['dog']
    name: str


Pet = Annotated[Union[Cat, Dog], Field(discriminator='pet_type')]


class Model(BaseModel):
    pet: Pet
    n: int


app = FastAPI()


@app.get("/", response_model=Model)
async def root():
    model = Model(pet={'pet_type': 'cat', 'color': 'black', 'black_name': 'felix'}, n=1)
    return model

Description

• Open the web browser and try to get endpoint /docs or /redoc. It should generate documentation and return it, but instead it returns

In the console I see error ``` pydantic_core._pydantic_core.ValidationError: 3 validation errors for OpenAPI components.schemas.Model.Schema.properties.pet.Schema.discriminator.mapping.cat Input should be a valid string [type=string_type, input_value={'discriminator': {'mappi...nts/schemas/WhiteCat'}]}, input_type=dict] For further information visit https://errors.pydantic.dev/2.6/v/string_type components.schemas.Model.Schema.properties.pet.bool Input should be a valid boolean [type=bool_type, input_value={'discriminator': {'mappi.../Dog'}], 'title': 'Pet'}, input_type=dict] For further information visit https://errors.pydantic.dev/2.6/v/bool_type components.schemas.Model.Reference.$ref Field required [type=missing, input_value={'properties': {'pet': {'...odel', 'type': 'object'}, input_type=dict] For further information visit https://errors.pydantic.dev/2.6/v/missing ```

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.109.0

Pydantic Version

2.6.0

Python Version

3.11.6

Additional Context

There is an Open issue for Pydantic.
However, just dumping the model to JSON works for me.

model = Model(pet={'pet_type': 'cat', 'color': 'black', 'black_name': 'felix'}, n=1)
print(model.model_json_schema())

output

{
    "$defs":
    {
        "BlackCat":
        {
            "properties":
            {
                "pet_type":
                {
                    "const": "cat",
                    "title": "Pet Type"
                },
                "color":
                {
                    "const": "black",
                    "title": "Color"
                },
                "black_name":
                {
                    "title": "Black Name",
                    "type": "string"
                }
            },
            "required":
            [
                "pet_type",
                "color",
                "black_name"
            ],
            "title": "BlackCat",
            "type": "object"
        },
        "Dog":
        {
            "properties":
            {
                "pet_type":
                {
                    "const": "dog",
                    "title": "Pet Type"
                },
                "name":
                {
                    "title": "Name",
                    "type": "string"
                }
            },
            "required":
            [
                "pet_type",
                "name"
            ],
            "title": "Dog",
            "type": "object"
        },
        "WhiteCat":
        {
            "properties":
            {
                "pet_type":
                {
                    "const": "cat",
                    "title": "Pet Type"
                },
                "color":
                {
                    "const": "white",
                    "title": "Color"
                },
                "white_name":
                {
                    "title": "White Name",
                    "type": "string"
                }
            },
            "required":
            [
                "pet_type",
                "color",
                "white_name"
            ],
            "title": "WhiteCat",
            "type": "object"
        }
    },
    "properties":
    {
        "pet":
        {
            "discriminator":
            {
                "mapping":
                {
                    "cat":
                    {
                        "discriminator":
                        {
                            "mapping":
                            {
                                "black": "#/$defs/BlackCat",
                                "white": "#/$defs/WhiteCat"
                            },
                            "propertyName": "color"
                        },
                        "oneOf":
                        [
                            {
                                "$ref": "#/$defs/BlackCat"
                            },
                            {
                                "$ref": "#/$defs/WhiteCat"
                            }
                        ]
                    },
                    "dog": "#/$defs/Dog"
                },
                "propertyName": "pet_type"
            },
            "oneOf":
            [
                {
                    "discriminator":
                    {
                        "mapping":
                        {
                            "black": "#/$defs/BlackCat",
                            "white": "#/$defs/WhiteCat"
                        },
                        "propertyName": "color"
                    },
                    "oneOf":
                    [
                        {
                            "$ref": "#/$defs/BlackCat"
                        },
                        {
                            "$ref": "#/$defs/WhiteCat"
                        }
                    ]
                },
                {
                    "$ref": "#/$defs/Dog"
                }
            ],
            "title": "Pet"
        },
        "n":
        {
            "title": "N",
            "type": "integer"
        }
    },
    "required":
    [
        "pet",
        "n"
    ],
    "title": "Model",
    "type": "object"
}

[YuriiMotov]

Looks like a FastAPI bug.
At the same time, response data validation works. The problem is only with schema creation

[MickVermeulen]

Could we turn this into an issue to increase visibility? I feel like this ticks all the boxes to be a proper issue.

[JeremyCraigMartinez]

Would model_dump help here?

[MickVermeulen]

Am running into the same issue, I don't think the issue is that the Pydantic model cannot be serialised. The issue is that the OpenAPI schema that's generated is not valid, hence the docs crash.

[akalex]

I came up with a workaround to prevent FastAPI from crashing. It looks ugly somehow, but it solves the immediate problem.

from fastapi.openapi.utils import get_openapi

def get_openapi_schema(app: FastAPI) -> dict:
    openapi_schema = get_openapi(title=app.title, version=app.version, description=app.description, routes=app.routes)
    openapi_schema["components"]["schemas"][SCHEMA_ID] = Model.model_json_schema(
            ref_template=REF_TEMPLATE
     )
    openapi_schema["components"]["schemas"]["Dog"] = Dog.model_json_schema(
        ref_template=REF_TEMPLATE
    )
    openapi_schema["components"]["schemas"]["Cat"] = Cat.model_json_schema(
        ref_template=REF_TEMPLATE
    )
    
...
# Override default OpenAPI documentation
app.openapi_schema = get_openapi_schema(app)

[glebmxyz]

Hey! I think docs generation breaks because FastAPI doesn't generate a definition for union types. So they don't have a $ref and get inlined in the discriminator.mapping.

I found a workaround:

from typing import Annotated, Literal

from fastapi import FastAPI
from pydantic import BaseModel, Field, RootModel


class BlackCat(BaseModel):
    pet_type: Literal['cat']
    color: Literal['black']
    black_name: str


class WhiteCat(BaseModel):
    pet_type: Literal['cat']
    color: Literal['white']
    white_name: str


class Cat(RootModel[Annotated[BlackCat | WhiteCat, Field(discriminator='color')]]): ...


class Dog(BaseModel):
    pet_type: Literal['dog']
    name: str


Pet = Annotated[Cat | Dog, Field(discriminator='pet_type')]


class Model(BaseModel):
    pet: Pet
    n: int


app = FastAPI()


@app.get('/', response_model=Model)
async def root():
    model = Model(pet={'pet_type': 'cat', 'color': 'black', 'black_name': 'felix'}, n=1)
    return model

There we use RootModel to force FastAPI to treat union type as a model. Then we inherit it to get a proper $ref and title.

[akalex]

Hey @glebmxyz,
Yes, that works great for me.

[ariofrio]

This prevents FastAPI from immediately crashing, but fails when trying to create an e.g. Cat(BlackCat()) and serialize it:

Unable to extract tag using discriminator 'pet_type' [type=union_tag_not_found, input_value=Cat(root=BlackCat...xt', ...)])), input_type=Cat]