After a model change, a FastAPI app's generated client shows separate Item-Input and Item-Output types: why does FastAPI split a schema, and what does turning that off cost?
answer
- two JSON Schema modes per model
- split only when they differ
- computed fields and serialization aliases
- False documents the input shape
basics
~20 sFastAPI builds request schemas in Pydantic's validation mode and response schemas in serialization mode; when one model's two schemas differ, it publishes Item-Input and Item-Output. separate_input_output_schemas=False publishes the input shape for both, which can misdescribe responses.
solid answer
~40 sPydantic 2 can produce two JSON Schemas for one model: validation mode for what it accepts and serialization mode for what it emits. FastAPI uses the first for request bodies and the second for responses, and when a model needs both and they differ it names them `Item-Input` and `Item-Output`. With Pydantic 2.14 a plain model with defaults does not split; a `computed_field`, a `serialization_alias` or `json_schema_serialization_defaults_required=True` does, so a model change is the usual trigger. `FastAPI(separate_input_output_schemas=False)` restores one `Item` built in validation mode, which misleads once the shapes really differ: a field with `serialization_alias="userId"` is documented as `user_id` while responses send `userId`. Models with computed fields still split. Usually the better fix is to accept the split and regenerate, or declare separate input and public models.
code
python · 45 linesfrom fastapi import FastAPI
from pydantic import BaseModel, Field, computed_field
class Item(BaseModel):
name: str
description: str | None = None # a default alone does not split
class Price(BaseModel):
net: float
tax_rate: float = 0.2
@computed_field
@property
def gross(self) -> float:
return self.net * (1 + self.tax_rate)
class Account(BaseModel):
user_id: int = Field(serialization_alias="userId")
def schema_names(**kwargs) -> list[str]:
app = FastAPI(**kwargs)
@app.post("/items")
def create_item(item: Item) -> Item:
return item
@app.post("/prices")
def create_price(price: Price) -> Price:
return price
@app.post("/accounts")
def create_account(account: Account) -> Account:
return account
return sorted(app.openapi()["components"]["schemas"])
print(schema_names())
# [... 'Account-Input', 'Account-Output', 'Item', 'Price-Input', 'Price-Output', ...]
print(schema_names(separate_input_output_schemas=False))
# [... 'Account', 'Item', 'Price-Input', 'Price-Output', ...]go deeper
Know that one Pydantic model can appear twice in the schema, as Item-Input and Item-Output, when its input and output shapes differ.
Explain validation versus serialization mode and list the model features that make them differ, including why a plain default no longer does.
Diagnose a client-type change from the schema, and show how turning the split off misdescribes aliased fields that generated clients rely on.
Decide whether the team names input and output models explicitly or accepts FastAPI's suffixes, and keep the off switch a dated bridge, not a default.
## Two schemas for one model **Pydantic 2** can describe a model in two **JSON Schema modes**. *Validation mode* describes what the model accepts as input; *serialization mode* describes what it produces when dumped. FastAPI uses validation mode for request bodies and parameters, and serialization mode for `response_model` and return annotations. When a model is used both ways and its two schemas are identical, FastAPI publishes one component, `Item`. When they differ, it publishes both, named `Item-Input` and `Item-Output`, and references each from the right place. A client generator then emits two types, which is the symptom in the question. ## What makes the two schemas differ | Model feature | Input schema | Output schema | Splits? | |---|---|---|---| | a field with a default, such as `description: str \| None = None` | optional | optional | no | | `@computed_field` property `gross` | absent | present and required | yes | | `Field(serialization_alias="userId")` | `user_id` | `userId` | yes | | `model_config = ConfigDict(json_schema_serialization_defaults_required=True)` | defaults optional | defaults required | yes | The first row surprises people who read FastAPI's page on this feature, which shows a plain model with a `None` default splitting. That was true with early Pydantic 2; since Pydantic 2.4, fields with defaults are not marked required in serialization mode unless the model opts in with `json_schema_serialization_defaults_required`, and FastAPI's own test for that example expects a single `Item`. So when the types suddenly split, look for a model change that made output differ from input. ## How a generated client sees it For the `Price` model with a computed `gross`, the two components differ like this: - `Price-Input` lists `net` and `tax_rate`, with only `net` required, because `tax_rate` has a default. - `Price-Output` lists `net`, `tax_rate` and `gross`, with `net` and `gross` required, because the computed field is always emitted. - The request body of the create operation references `Price-Input`, and its `200` response references `Price-Output`. A typed client therefore gets two types: the function that sends a price takes the input type, and the function that reads one returns the output type. Frontend code that passed a response object straight back as a request, or that imported a single `Price` type, stops compiling. That is the noise the team sees, but it is the client finally describing the API accurately. Aliases work the same way. FastAPI dumps response models by alias by default (`response_model_by_alias=True`), so a field with `serialization_alias="userId"` really is sent as `userId`, and only the output schema says so. ## Diagnosing the client change 1. Fetch `/openapi.json`, or call `app.openapi()`, and list `components.schemas` for names ending in `-Input` and `-Output`. 2. Compare each pair's `properties` and `required`: the difference names the feature from the table. 3. Find the commit that added it, usually a computed field, an alias for a camelCase API, or the config flag. 4. Decide whether the client should see two types, which is the precise description, or whether the model should change. ## What separate_input_output_schemas=False costs `FastAPI(separate_input_output_schemas=False)` exists, according to FastAPI's docs, mainly for teams with already generated clients that are not ready to change. It makes FastAPI build one schema per model in **validation mode** and use it for responses too. The costs: - **Aliases are misdescribed.** With `serialization_alias="userId"`, the single schema says `user_id`, while the response body really carries `userId`. A generated client then reads a field that is never there. - **Required-ness is lost.** Fields that are always present in output, because of the config flag, are documented as optional, so clients add needless null checks. - **Computed fields are the exception.** A model with a `computed_field` still gets `-Input` and `-Output` schemas, because FastAPI keeps the output schema whenever a model has computed fields; otherwise the field would vanish from the docs. - **Overrides must repeat it.** A custom `app.openapi()` built on `get_openapi` must pass `separate_input_output_schemas` itself, since that function defaults to `True`. ## Choosing a fix - **Accept the split** and regenerate the client: the two types are the truthful contract. - **Declare explicit models**, such as a create model for input and a public model for output, so names are yours rather than suffixes FastAPI chose; the response-model lesson covers that layout. - **Use `False` as a bridge**, with a dated plan to remove it, and never on models whose aliases or computed fields make the shapes differ.
- In FastAPI with separate_input_output_schemas=False, why does a model with a computed_field still get Item-Input and Item-Output?A computed field exists only when the model is serialized. Built in validation mode alone, the schema would drop it, and the docs would hide a field every response carries. FastAPI therefore keeps serialization mode for models with computed fields, whatever the flag says.
- In FastAPI, how do you make an output schema mark defaulted fields as required without a computed field?Set `model_config = ConfigDict(json_schema_serialization_defaults_required=True)` on the Pydantic model. Serialization mode then marks every defaulted field as required, since a dumped model always carries it, and FastAPI splits that model into `-Input` and `-Output` schemas.
- FastAPI splits every model that has a field with a default value.
- separate_input_output_schemas=False makes the docs describe responses exactly.
- The -Input and -Output names mean the model is used incorrectly.
- A custom get_openapi override inherits the app's separate_input_output_schemas setting.
- Computed fields disappear from responses when the flag is False.
Assumes FastAPI 0.143 with Pydantic 2.14; since Pydantic 2.4, defaulted fields are not required in serialization mode, so a model with plain defaults no longer splits as older FastAPI docs show.