fixes #4168: To describe tuple types, allow an array of schemas as a type of array items, according to json schema specification.

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue 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 pydantic import BaseModel
from fastapi import FastAPI

from typing import Tuple

class FooModel(BaseModel):
  prop: Tuple[int, str]


app = FastAPI()

@app.get('/', response_model=FooModel)
def get_foo():
 return {"prop": (0, 'ok')}

print(app.openapi())

Description

Summary

The above code must be failed with a ValidationError like this:

Traceback (most recent call last):
  File "<pyshell#3>", line 1, in <module>
    a()
  File "<pyshell#1>", line 17, in a
    print(app.openapi())
  File "/usr/local/lib/python39/lib/site-packages/fastapi/applications.py", line 136, in openapi
    self.openapi_schema = get_openapi(
  File "/usr/local/lib/python39/lib/site-packages/fastapi/openapi/utils.py", line 410, in get_openapi
    return jsonable_encoder(OpenAPI(**output), by_alias=True, exclude_none=True)  # type: ignore
  File "pydantic/main.py", line 406, in pydantic.main.BaseModel.__init__
pydantic.error_wrappers.ValidationError: 2 validation errors for OpenAPI
components -> schemas -> FooModel -> properties -> prop -> items
  value is not a valid dict (type=type_error.dict)
components -> schemas -> FooModel -> $ref
  field required (type=value_error.missing)

in fastapi.openapi.models in line 103~142

class Schema(BaseModel):
    ref: Optional[str] = Field(None, alias="$ref")
    title: Optional[str] = None
    multipleOf: Optional[float] = None
    maximum: Optional[float] = None
    exclusiveMaximum: Optional[float] = None
    minimum: Optional[float] = None
    exclusiveMinimum: Optional[float] = None
    maxLength: Optional[int] = Field(None, gte=0)
    minLength: Optional[int] = Field(None, gte=0)
    pattern: Optional[str] = None
    maxItems: Optional[int] = Field(None, gte=0)
    minItems: Optional[int] = Field(None, gte=0)
    uniqueItems: Optional[bool] = None
    maxProperties: Optional[int] = Field(None, gte=0)
    minProperties: Optional[int] = Field(None, gte=0)
    required: Optional[List[str]] = None
    enum: Optional[List[Any]] = None
    type: Optional[str] = None
    allOf: Optional[List["Schema"]] = None
    oneOf: Optional[List["Schema"]] = None
    anyOf: Optional[List["Schema"]] = None
    not_: Optional["Schema"] = Field(None, alias="not")
    items: Optional["Schema"] = None
    properties: Optional[Dict[str, "Schema"]] = None
    additionalProperties: Optional[Union["Schema", Reference, bool]] = None
    description: Optional[str] = None
    format: Optional[str] = None
    default: Optional[Any] = None
    nullable: Optional[bool] = None
    discriminator: Optional[Discriminator] = None
    readOnly: Optional[bool] = None
    writeOnly: Optional[bool] = None
    xml: Optional[XML] = None
    externalDocs: Optional[ExternalDocumentation] = None
    example: Optional[Any] = None
    deprecated: Optional[bool] = None

    class Config:
        extra: str = "allow"

It seems Schema.items should accept an array of schemas according to the JSON schema spec, but only the type Schema is allowed in the current code.

Operating System

Linux, Windows

Operating System Details

No response

FastAPI Version

0.70.0

Python Version

Python 3.9.5

Additional Context

No response

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue 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 Tuple
from fastapi import FastAPI
from pydantic import BaseModel


class FooArgs(BaseModel):
    bars: Tuple[str, str]


app = FastAPI()


@app.post("/foo")
def foo(args: FooArgs):
    ...

Description

If you try to retrieve the /openapi.json, the FooArgs get a validation error:

  File ".../lib/python3.9/site-packages/fastapi/openapi/utils.py", line 410, in get_openapi
    return jsonable_encoder(OpenAPI(**output), by_alias=True, exclude_none=True)  # type: ignore
  File "pydantic/main.py", line 406, in pydantic.main.BaseModel.__init__
pydantic.error_wrappers.ValidationError: 2 validation errors for OpenAPI
components -> schemas -> FooArgs -> properties -> bars -> items
  value is not a valid dict (type=type_error.dict)
components -> schemas -> FooArgs -> $ref
  field required (type=value_error.missing)

This error is new to fastapi>=0.68, it does not happen with fastapi==0.67.0.

I think this is related to Pydantic coercing Tuple[str, str] into Dict[str, str] somewhere?

Things that don't cause this error:

class FooArgs(BaseModel):
    bars: Tuple[str]

class FooArgs(BaseModel):
    bars: Tuple[str, ...]

This that do cause this error:

class FooArgs(BaseModel):
    bars: Tuple[str, str]

class FooArgs(BaseModel):
    bars: Tuple[int, str]

class FooArgs(BaseModel):
    bars: Tuple[str, str, str]  # etc.

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.68.1

Python Version

3.9.1 (also seeing this in 3.8.*)

Additional Context

Seems pretty likely that this commit introduced it, but there's a lot going on so I'm not sure where:

https://github.com/tiangolo/fastapi/commit/97fa743ecb5a716fa0223a7463cb83f3f0df494c#diff-4939896f79697822446463d5d6dfbf7a0ea5805c46565d355c7305d86f3405c7

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue 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 fastapi import FastAPI
from pydantic import BaseModel, confloat

app = FastAPI()

LngLat = Tuple[confloat(ge=-180.0, le=180.0), confloat(ge=-90, le=90)]

class Viewport(BaseModel):
    sw: LngLat
    ne: LngLat

@app.get('/viewport', response_model=Viewport)
def get_viewport():
    return Viewport(sw=[-93, 36], ne=[-92, 37])

Description

The example code I've provided causes the openapi docs page to crash, with the following error displayed:

Failed to load API definition. Errors Fetch error Internal Server Error /openapi.json

Due to the following stack trace:

  File "/Users/hansbrende/miniconda3/envs/facade-api/lib/python3.8/site-packages/fastapi/applications.py", line 161, in openapi
    return JSONResponse(self.openapi())
  File "/Users/hansbrende/miniconda3/envs/facade-api/lib/python3.8/site-packages/fastapi/applications.py", line 136, in openapi
    self.openapi_schema = get_openapi(
  File "/Users/hansbrende/miniconda3/envs/facade-api/lib/python3.8/site-packages/fastapi/openapi/utils.py", line 411, in get_openapi
    return jsonable_encoder(OpenAPI(**output), by_alias=True, exclude_none=True)  # type: ignore
  File "pydantic/main.py", line 406, in pydantic.main.BaseModel.__init__
pydantic.error_wrappers.ValidationError: 3 validation errors for OpenAPI
components -> schemas -> Viewport -> properties -> sw -> items
  value is not a valid dict (type=type_error.dict)
components -> schemas -> Viewport -> properties -> ne -> items
  value is not a valid dict (type=type_error.dict)
components -> schemas -> Viewport -> $ref
  field required (type=value_error.missing)

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.68.0

Python Version

Python 3.8.10

Additional Context

No response

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue 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, Dict, Tuple

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Answers(BaseModel):
    answers: Dict[str, List[Tuple[str, float]]] = {}

@app.get("/qa", response_model=Answers)
async def qatask(request: str):
    return Answers()

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("bugfind:app", host="0.0.0.0", port=5000, reload=True,
                workers=1)  # , debug=True)

Description

open http://localhost:5000/docs or http://localhost:5000/openapi.json and you will see the error in the logs.

Operating System

Linux

Operating System Details

ubuntu 20.04

FastAPI Version

0.68.1

Python Version

3.8.10

Additional Context

There was a bug #383 a while ago reporting the same problem but closed. This new issue here is in order to reopen that bug as it still isn't solved or reappeared since then. Fell free to close this new issue and reopen the old bug if that is preferred.

this is the error:

Traceback (most recent call last):
  File "//home/name/.local/lib/python3.8/site-packages/uvicorn/protocols/http/h11_impl.py", line 373, in run_asgi
    result = await app(self.scope, self.receive, self.send)
  File "//home/name/.local/lib/python3.8/site-packages/uvicorn/middleware/proxy_headers.py", line 75, in __call__
    return await self.app(scope, receive, send)
  File "//home/name/.local/lib/python3.8/site-packages/fastapi/applications.py", line 208, in __call__
    await super().__call__(scope, receive, send)
  File "//home/name/.local/lib/python3.8/site-packages/starlette/applications.py", line 112, in __call__
    await self.middleware_stack(scope, receive, send)
  File "//home/name/.local/lib/python3.8/site-packages/starlette/middleware/errors.py", line 181, in __call__
    raise exc from None
  File "//home/name/.local/lib/python3.8/site-packages/starlette/middleware/errors.py", line 159, in __call__
    await self.app(scope, receive, _send)
  File "//home/name/.local/lib/python3.8/site-packages/starlette/exceptions.py", line 82, in __call__
    raise exc from None
  File "//home/name/.local/lib/python3.8/site-packages/starlette/exceptions.py", line 71, in __call__
    await self.app(scope, receive, sender)
  File "//home/name/.local/lib/python3.8/site-packages/starlette/routing.py", line 580, in __call__
    await route.handle(scope, receive, send)
  File "//home/name/.local/lib/python3.8/site-packages/starlette/routing.py", line 241, in handle
    await self.app(scope, receive, send)
  File "//home/name/.local/lib/python3.8/site-packages/starlette/routing.py", line 52, in app
    response = await func(request)
  File "//home/name/.local/lib/python3.8/site-packages/fastapi/applications.py", line 161, in openapi
    return JSONResponse(self.openapi())
  File "//home/name/.local/lib/python3.8/site-packages/fastapi/applications.py", line 136, in openapi
    self.openapi_schema = get_openapi(
  File "//home/name/.local/lib/python3.8/site-packages/fastapi/openapi/utils.py", line 410, in get_openapi
    return jsonable_encoder(OpenAPI(**output), by_alias=True, exclude_none=True)  # type: ignore
  File "pydantic/main.py", line 406, in pydantic.main.BaseModel.__init__
pydantic.error_wrappers.ValidationError: 4 validation errors for OpenAPI
components -> schemas -> Answers -> properties -> answers -> additionalProperties -> items -> items
  value is not a valid dict (type=type_error.dict)
components -> schemas -> Answers -> properties -> answers -> additionalProperties -> $ref
  field required (type=value_error.missing)
components -> schemas -> Answers -> properties -> answers -> additionalProperties
  value could not be parsed to a boolean (type=type_error.bool)
components -> schemas -> Answers -> $ref
  field required (type=value_error.missing)

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue 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

# main.py

import uvicorn
from fastapi import FastAPI, Form

app = FastAPI()

@app.post("/")
def hello(arg: tuple[int, int] = Form(...)) -> str:
    pass

if __name__ == "__main__":
    uvicorn.run("main:app", port=8080)

Description

1. Run pip install uvicorn fastapi==0.68.0.
2. Run python ./main.py
3. Hit localhost:8080/docs, observe internal server error with below validation errors:

pydantic.error_wrappers.ValidationError: 2 validation errors for OpenAPI
components -> schemas -> Body_hello__post -> properties -> arg -> items
  value is not a valid dict (type=type_error.dict)
components -> schemas -> Body_hello__post -> $ref
  field required (type=value_error.missing)

4. Run pip install fastapi==0.67.0
5. Hit localhost:8080/docs, observe that endpoint documentation is successfully generated.

Operating System

Linux

Operating System Details

Ubuntu 20.04

FastAPI Version

0.68.0 has bug, 0.67.0 does not have bug.

Python Version

3.9

Additional Context

Any use of tuple in an input (Form, and BaseModel as JSON) or output (BaseModel as JSON) results in above error.

This PR is meant to fix issues (https://github.com/tiangolo/fastapi/issues/3665, https://github.com/tiangolo/fastapi/issues/3782) encountered generating openapi.json with nested models that have iterable-typed attributes (e.g. Tuple or List).

Briefly, this behavior did not occur with 0.67.0, and was introduced in 0.68.0. Bisecting the issue led me to the following commit https://github.com/tiangolo/fastapi/commit/97fa743ecb5a716fa0223a7463cb83f3f0df494c.

As per the error raised when using nested schemas of iterables:

pydantic.error_wrappers.ValidationError: 2 validation errors for OpenAPI
components -> schemas -> BuggyItem -> properties -> items -> items -> items
  value is not a valid dict (type=type_error.dict)
components -> schemas -> BuggyItem -> $ref
  field required (type=value_error.missing)

I realized that there must be an issue when initializing the OpenAPI model, and specifically the items field of the Schema. This makes sense, since the commit introduced changes to the specification of the OpenAPI model.

And indeed, consider that we have the following Model to add to the openAPI specification:

class BuggyItem(pydantic.BaseModel):
    items: List[Tuple[str, str]]

We have to instantiate a Schema with

{
  "items": {
    "title": "Items",
    "type": "array",
    "items": {
      "type": "array",
      "items": [{ "type": "string" }, { "type": "string" }]
    }
  }
}

In other words, the definition of the Schema.items attribute cannot be

    items: Optional["Schema"] = None

But must be

    items: Optional[Union["Schema", List["Schema"]]] = None

Which is the change introduced in this commit.

Hopefully this is helpful, let me know if there is anything that I can add to this PR!