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 List, Optional
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class TreeNode(BaseModel):
    name: str
    children: Optional[List["TreeNode"]] = None

TreeNode.update_forward_refs()

@app.get("/tree", response_model=TreeNode)
def get_tree():
    return TreeNode(
        name="root",
        children=[
            TreeNode(name="child1"),
            TreeNode(name="child2", children=[TreeNode(name="grandchild")])
        ]
    )

Description

I’m trying to use a recursive Pydantic model with optional children. The model works when I return it directly from the endpoint, but the generated OpenAPI schema is invalid.

Swagger UI fails to render the model correctly.

ReDoc shows null for children instead of a list of objects.

I expected OpenAPI to correctly represent a recursive array structure where children can be empty or null.

Operating System

macOS

Operating System Details

No response

FastAPI Version

FastAPI Version: 0.121.x

Pydantic Version

Pydantic Version: 2.x

Python Version

Python Version: 3.14

Additional Context

I’ve tried update_forward_refs() and using typing.Self instead of string literals for recursion, but the OpenAPI spec still doesn’t generate correctly. Is there a recommended pattern for recursive models with optional children in FastAPI v0.121 + Pydantic v2?