Separate I/O schemas inconsistencies

[slafs]

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 decimal import Decimal

import pytest
from fastapi import FastAPI, status
from pydantic import BaseModel, ConfigDict


def get_app(
    separate_input_output_schemas: bool,
    json_schema_serialization_defaults_required: bool,
):
    class Model(BaseModel):
        model_config = ConfigDict(
            json_schema_serialization_defaults_required=json_schema_serialization_defaults_required,
        )

        foo: int = 42
        bar: Decimal  # Decimal has different schemas for input (validation) and output (serialization)

    app = FastAPI(separate_input_output_schemas=separate_input_output_schemas)

    @app.post(
        "/",
        responses={
            status.HTTP_402_PAYMENT_REQUIRED: {
                "model": Model,
            },
        },
    )
    def root(model: Model) -> Model:
        return model

    return app


@pytest.mark.parametrize("json_schema_serialization_defaults_required", [True, False])
def test_suppress_separate_io_models(
    json_schema_serialization_defaults_required: bool,
):
    """
    Case #1 - this works fine, skip this function if you want.

    Setting separate_input_output_schemas to False
    suppresses generating separate schemas for input and output
    regardless of json_schema_serialization_defaults_required value.
    """
    app = get_app(
        separate_input_output_schemas=False,
        json_schema_serialization_defaults_required=json_schema_serialization_defaults_required,
    )
    schema = app.openapi()

    assert "Model" in schema["components"]["schemas"]
    assert "Model-Input" not in schema["components"]["schemas"]
    assert "Model-Output" not in schema["components"]["schemas"]


@pytest.mark.parametrize("json_schema_serialization_defaults_required", [True, False])
def test_separate_io_models(
    json_schema_serialization_defaults_required: bool,
):
    """
    Case #2

    Setting separate_input_output_schemas to True
    generates separate schemas for input and output
    regardless of json_schema_serialization_defaults_required value (because we have the Decimal field),
    but (bug?) generates the "Input" schema for the custom response.
    """

    app = get_app(
        separate_input_output_schemas=True,
        json_schema_serialization_defaults_required=json_schema_serialization_defaults_required,
    )

    schema = app.openapi()

    assert "Model" not in schema["components"]["schemas"]
    assert "Model-Input" in schema["components"]["schemas"]
    assert "Model-Output" in schema["components"]["schemas"]

    # Separate Input model for the request
    assert (
        "Model-Input"
        in schema["paths"]["/"]["post"]["requestBody"]["content"]["application/json"]["schema"]["$ref"]
    )

    # Separate Output model for the 200 response
    assert (
        "Model-Output"
        in schema["paths"]["/"]["post"]["responses"]["200"]["content"]["application/json"]["schema"]["$ref"]
    )

    # Separate Output model for the 402 response
    # This fails!
    assert (
        "Model-Output"
        in schema["paths"]["/"]["post"]["responses"]["402"]["content"]["application/json"]["schema"]["$ref"]
    )

Description

I think I've spotted two issues regarding the separate Input and Output OpenAPI schemas topic.

1. The responses -> status_code -> model option for the given path operation generates an Input model instead of the Output one. See the test_separate_io_models test.
2. Suppressing separate models on FastAPI level works fine (see test_suppress_separate_io_models), but enabling it is more subtle than the docs are suggesting.
   1. As of Pydantic v2.4.0 (Make fields with defaults not required in the serialization schema by default pydantic/pydantic#7275) fields with defaults are not required in the serialization schema by default. This means you have to explicitly opt-in to have such models generate different I/O schemas by setting json_schema_serialization_defaults_required config value to True. My example code doesn't actually show this, but you can observe it by commenting the bar field and noticing that only the Model schema does get generated when you set json_schema_serialization_defaults_required config to False and there is no -Input nor -Output models.
   2. Having a default value or not on a given field is not the only way to have different input and output schemas for the corresponding model. In Pydantic v2, one can define a field that yields a different schema for validation (input) and serialization (output) without giving it a default value. One built-in type with such behaviour is decimal.Decimal class from the stdlib. However, the same docs seem to claim that the separation is only "depending on if they have default values".

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.104.1

Pydantic Version

2.5.1

Python Version

Python 3.10.9

Additional Context

No response

[slafs]

@Kludex sorry for pinging you directly. Is there any chance you could turn this into an issue?

[slafs]

Issue 1. is addressed in this PR #11517