OpenAPI Generated for NamedTuple is Object, Not List #9310

michaeligreenberg · 2023-03-24T21:38:33Z

michaeligreenberg
Mar 24, 2023

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 NamedTuple, Union

from fastapi import FastAPI
from pydantic import BaseModel

class Location(NamedTuple):
    latitude: float
    longitude: float

class Trip(BaseModel):
    start: Location
    end: Location

app = FastAPI()

@app.post("/trip")
def create_trip(trip: Trip):
    return {"status": "OK"}

Description

The Location NamedTuple provides constraints and a better interface for accessing a [lat,long] coordinate array.
The /openapi.json endpoint produces the following schema definition of Location:

"Location":
{
    "title": "Location",
    "required":
    [
        "latitude",
        "longitude"
    ],
    "type": "object",
    "properties":
    {
        "latitude":
        {
            "title": "Latitude",
            "type": "number"
        },
        "longitude":
        {
            "title": "Longitude",
            "type": "number"
        }
    }
}

Note that it defines Location to be an object with named properties; this is incompatible with what the /trip endpoint actually accepts.

Expected behavior is to define Location as a collection of items with minimum size 2, maximum size 2, and both entires of type number.

Operating System

Linux

Operating System Details

ubuntu 20.04 run via Docker

FastAPI Version

0.95.0

Python Version

3.8.10

Additional Context

No response

caniko · 2024-08-08T16:14:47Z

caniko
Aug 8, 2024

In version 0.112 I get:

    UploadBenchmarkingData:
      prefixItems:
      - type: string
        format: duration
        title: Upload Interval
      - type: integer
        exclusiveMinimum: 0.0
        title: Payload Byte Size
      - type: string
        title: Continent
      - type: string
        pattern: ^\w{2}$
        title: Country
      - type: string
        title: City
      type: array
      maxItems: 5
      minItems: 5

For:

UploadBenchmarkingData = NamedTuple(
    "UploadBenchmarkingData",
    [
        ("upload_interval", datetime.timedelta),
        ("payload_byte_size", PositiveInt),
        ("continent", str),
        ("country", CountryAlpha2),
        ("city", str),
    ],
)

This is invalid, arrays are not supposed to have prefixItems, not sure what the right field is though.

0 replies

MythicalCosmic · 2025-11-02T17:56:56Z

MythicalCosmic
Nov 2, 2025

The issue is that NamedTuple doesn't work well with FastAPI/Pydantic because of a schema mismatch. Use Pydantic BaseModel.

0 replies

CodeKraken-cmd · 2025-11-02T19:22:40Z

CodeKraken-cmd
Nov 2, 2025

FastAPI and Pydantic treat typing.NamedTuple as an object with named fields, so the generated schema is an object with latitude and longitude. That is expected. If your endpoint should accept a two-element array like [lat, lon], model it as a tuple or a constrained list instead of a NamedTuple. On newer FastAPI with OpenAPI 3.1, tuples appear in JSON Schema using prefixItems. That is valid JSON Schema 2020-12, but some tools that only understand OpenAPI 3.0 may not handle it. You have three practical choices:

Use a fixed-length tuple if the client can handle OpenAPI 3.1
Use a constrained list if you need 3.0-compatible tooling
Keep an object model if you prefer explicit field names and add range validation

Option A. Two-element numeric tuple (OpenAPI 3.1 will use prefixItems)

from typing import Tuple
from fastapi import FastAPI
from pydantic import BaseModel

Coord = Tuple[float, float]

class Trip(BaseModel):
    start: Coord
    end: Coord

app = FastAPI()  # emits OpenAPI 3.1 by default in recent versions

@app.post("/trip")
def create_trip(trip: Trip):
    return {"status": "OK"}

Option B. Constrained list with exact length 2 (plays nicely with OpenAPI 3.0)

from fastapi import FastAPI
from pydantic import BaseModel, conlist

Coord = conlist(float, min_length=2, max_length=2)

class Trip(BaseModel):
    start: Coord
    end: Coord

app = FastAPI(openapi_version="3.0.3")  # optional if you want to avoid prefixItems

@app.post("/trip")
def create_trip(trip: Trip):
    return {"status": "OK"}

Option C. Keep object shape with validation (explicit names and ranges)

from fastapi import FastAPI
from pydantic import BaseModel, Field

class Location(BaseModel):
    latitude: float = Field(ge=-90, le=90)
    longitude: float = Field(ge=-180, le=180)

class Trip(BaseModel):
    start: Location
    end: Location

app = FastAPI()

@app.post("/trip")
def create_trip(trip: Trip):
    return {"status": "OK"}

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

OpenAPI Generated for NamedTuple is Object, Not List #9310

Uh oh!

{{title}}

Uh oh!

Replies: 3 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

OpenAPI Generated for NamedTuple is Object, Not List #9310

Uh oh!

michaeligreenberg Mar 24, 2023

First Check

Commit to Help

Example Code

Description

Operating System

Operating System Details

FastAPI Version

Python Version

Additional Context

Replies: 3 comments

Uh oh!

Uh oh!

caniko Aug 8, 2024

Uh oh!

Uh oh!

MythicalCosmic Nov 2, 2025

Uh oh!

CodeKraken-cmd Nov 2, 2025

michaeligreenberg
Mar 24, 2023

caniko
Aug 8, 2024

MythicalCosmic
Nov 2, 2025

CodeKraken-cmd
Nov 2, 2025