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

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "fastapi==0.118.3",
#     "pydantic>=2.9.0",
# ]
# ///
import json
import typing
from fastapi import FastAPI
from pydantic import BaseModel


# Model using typing.Self for recursive structure
class Node(BaseModel):
    id: str
    children: list[typing.Self]


# FastAPI application
app = FastAPI()


@app.get("/node", response_model=Node)
def get_node():
    """Get a node with children."""
    return Node(
        id="root",
        children=[
            Node(id="child1", children=[]),
            Node(id="child2", children=[])
        ]
    )


if __name__ == "__main__":
    try:
        pydantic_schema = Node.model_json_schema()
        print(json.dumps(pydantic_schema, indent=2))
    except Exception as e:
        print(f"✗ Pydantic failed: {e}")

    openapi_schema = app.openapi()
    print(json.dumps(openapi_schema, indent=2))

Description

Generating the OpenAPI specification with a model that uses a field with typing.Self raises an error:
pydantic.errors.PydanticUserError: typing.Self is invalid in this context

This used to work, in FastAPI 0.118.x . This broke in 0.119 (and still broken in 0.121.1), where pydantic v1 compat code was introduced.

Generating the JSON schema using pydantic words, but not when it gets called through the fastAPI compat code.

Not that hard to workaround, by specifying the exact type or using generics, but we loose the nice subclass-ability and readability of Self.

Operating System

Linux

Operating System Details

No response

FastAPI Version

2.12.4

Pydantic Version

0.121.0

Python Version

Python 3.14.0

Additional Context

Run the example code with FastAPI 0.118.3 and you get a working OpenAPI spec.