🦖 Fix multiple upload file schema to be compatible with OAS 3.0 to make it work in Swagger UI by YuriiMotov · Pull Request #15069 · fastapi/fastapi

YuriiMotov · 2026-03-06T17:35:45Z

#14953 updated schema of byte fields to be in line with OAS 3.1.
But Swagger UI doesn't seem to fully support it and we have text fields instead of file pickers for multiple file upload fields (see #14975).

The idea of this PR is to make the schema of file upload fields backward compatible with OAS 3.0 (which is handled well by Swagger UI) by adding "format": "binary":

{
      "type": "string",
+     "format": "binary",
      "contentMediaType": "application/octet-stream",
}

OAS 3.1+ will just ignore it (see spec) and OAS 3.0 - compatible tools will just ignore contentMediaType (as it's not defined in OAS 3.0).

We have to handle separately situation when bytes are inside JSON (not file upload). To do this we need to somehow pass context (whether it's a File field or not) to bytes_schema.
Cloude Code suggested to do it by adding _FileUploadMarker marker. I reviewed and it looks good to me (after several iterations :))

Tested manually with the following app:

Details

from typing import Annotated

from fastapi import FastAPI, File, UploadFile
from pydantic import BaseModel

app = FastAPI()


# ---

@app.post("/upload-files-bytes")
async def upload_files_bytes(p: Annotated[list[bytes], File()]):
    return {"file_sizes": [len(file) for file in p] if p else None}


@app.post("/upload-files-uploadfile")
async def upload_files_uploadfile(p: Annotated[list[UploadFile], File()]):
    return {"file_sizes": [file.size for file in p] if p else None}


@app.post("/upload-file-bytes")
async def upload_file_bytes(p: Annotated[bytes, File()]):
    return {"file_sizes": len(p) if p else None}


@app.post("/upload-file-uploadfile")
async def upload_file_uploadfile(p: Annotated[UploadFile, File()]):
    return {"file_sizes": p.size if p else None}


# ---


@app.post("/opt-upload-files-bytes")
async def opt_upload_files_bytes(p: Annotated[list[bytes] | None, File()] = None):
    return {"file_sizes": [len(file) for file in p] if p else None}


@app.post("/opt-upload-files-uploadfile")
async def opt_upload_files_uploadfile(p: Annotated[list[UploadFile] | None, File()] = None):
    return {"file_sizes": [file.size for file in p] if p else None}


@app.post("/opt-upload-file-bytes")
async def opt_upload_file_bytes(p: Annotated[bytes | None, File()] = None):
    return {"file_sizes": len(p) if p else None}


@app.post("/opt-upload-file-uploadfile")
async def opt_upload_file_uploadfile(p: Annotated[UploadFile | None, File()] = None):
    return {"file_sizes": p.size if p else None}


# ---

class DataInput(BaseModel):
    description: str
    data: bytes

class DataInputBase64(DataInput):
    model_config = {"val_json_bytes": "base64"}


@app.post("/data")
def post_data(body: DataInput):  # Will NOT decode base64 (will return as is)
    content = body.data.decode("utf-8")
    return {"description": body.description, "content": content}


@app.post("/data-base64")
def post_data_base64(body: DataInputBase64):  # Will decode base64
    content = body.data.decode("utf-8")
    return {"description": body.description, "content": content}

Produced OpenAPI schema:

Details

{
  "openapi": "3.1.0",
  "info": {
    "title": "FastAPI",
    "version": "0.1.0"
  },
  "paths": {
    "/upload-files-bytes": {
      "post": {
        "summary": "Upload Files Bytes",
        "operationId": "upload_files_bytes_upload_files_bytes_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_upload_files_bytes_upload_files_bytes_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/upload-files-uploadfile": {
      "post": {
        "summary": "Upload Files Uploadfile",
        "operationId": "upload_files_uploadfile_upload_files_uploadfile_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_upload_files_uploadfile_upload_files_uploadfile_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/upload-file-bytes": {
      "post": {
        "summary": "Upload File Bytes",
        "operationId": "upload_file_bytes_upload_file_bytes_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_upload_file_bytes_upload_file_bytes_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/upload-file-uploadfile": {
      "post": {
        "summary": "Upload File Uploadfile",
        "operationId": "upload_file_uploadfile_upload_file_uploadfile_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_upload_file_uploadfile_upload_file_uploadfile_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/opt-upload-files-bytes": {
      "post": {
        "summary": "Opt Upload Files Bytes",
        "operationId": "opt_upload_files_bytes_opt_upload_files_bytes_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_opt_upload_files_bytes_opt_upload_files_bytes_post"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/opt-upload-files-uploadfile": {
      "post": {
        "summary": "Opt Upload Files Uploadfile",
        "operationId": "opt_upload_files_uploadfile_opt_upload_files_uploadfile_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_opt_upload_files_uploadfile_opt_upload_files_uploadfile_post"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/opt-upload-file-bytes": {
      "post": {
        "summary": "Opt Upload File Bytes",
        "operationId": "opt_upload_file_bytes_opt_upload_file_bytes_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_opt_upload_file_bytes_opt_upload_file_bytes_post"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/opt-upload-file-uploadfile": {
      "post": {
        "summary": "Opt Upload File Uploadfile",
        "operationId": "opt_upload_file_uploadfile_opt_upload_file_uploadfile_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_opt_upload_file_uploadfile_opt_upload_file_uploadfile_post"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/data": {
      "post": {
        "summary": "Post Data",
        "operationId": "post_data_data_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DataInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/data-base64": {
      "post": {
        "summary": "Post Data Base64",
        "operationId": "post_data_base64_data_base64_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DataInputBase64"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {

                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Body_opt_upload_file_bytes_opt_upload_file_bytes_post": {
        "properties": {
          "p": {
            "anyOf": [
              {
                "type": "string",
                "format": "binary",  <= Added
                "contentMediaType": "application/octet-stream"
              },
              {
                "type": "null"
              }
            ],
            "title": "P"
          }
        },
        "type": "object",
        "title": "Body_opt_upload_file_bytes_opt_upload_file_bytes_post"
      },
      "Body_opt_upload_file_uploadfile_opt_upload_file_uploadfile_post": {
        "properties": {
          "p": {
            "anyOf": [
              {
                "type": "string",
                "format": "binary",  <= Added
                "contentMediaType": "application/octet-stream"
              },
              {
                "type": "null"
              }
            ],
            "title": "P"
          }
        },
        "type": "object",
        "title": "Body_opt_upload_file_uploadfile_opt_upload_file_uploadfile_post"
      },
      "Body_opt_upload_files_bytes_opt_upload_files_bytes_post": {
        "properties": {
          "p": {
            "anyOf": [
              {
                "items": {
                  "type": "string",
                  "format": "binary",  <= Added
                  "contentMediaType": "application/octet-stream"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "P"
          }
        },
        "type": "object",
        "title": "Body_opt_upload_files_bytes_opt_upload_files_bytes_post"
      },
      "Body_opt_upload_files_uploadfile_opt_upload_files_uploadfile_post": {
        "properties": {
          "p": {
            "anyOf": [
              {
                "items": {
                  "type": "string",
                  "format": "binary",  <= Added
                  "contentMediaType": "application/octet-stream"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "P"
          }
        },
        "type": "object",
        "title": "Body_opt_upload_files_uploadfile_opt_upload_files_uploadfile_post"
      },
      "Body_upload_file_bytes_upload_file_bytes_post": {
        "properties": {
          "p": {
            "type": "string",
            "format": "binary",  <= Added
            "contentMediaType": "application/octet-stream",
            "title": "P"
          }
        },
        "type": "object",
        "required": [
          "p"
        ],
        "title": "Body_upload_file_bytes_upload_file_bytes_post"
      },
      "Body_upload_file_uploadfile_upload_file_uploadfile_post": {
        "properties": {
          "p": {
            "type": "string",
            "format": "binary",  <= Added
            "contentMediaType": "application/octet-stream",
            "title": "P"
          }
        },
        "type": "object",
        "required": [
          "p"
        ],
        "title": "Body_upload_file_uploadfile_upload_file_uploadfile_post"
      },
      "Body_upload_files_bytes_upload_files_bytes_post": {
        "properties": {
          "p": {
            "items": {
              "type": "string",
              "format": "binary",  <= Added
              "contentMediaType": "application/octet-stream"
            },
            "type": "array",
            "title": "P"
          }
        },
        "type": "object",
        "required": [
          "p"
        ],
        "title": "Body_upload_files_bytes_upload_files_bytes_post"
      },
      "Body_upload_files_uploadfile_upload_files_uploadfile_post": {
        "properties": {
          "p": {
            "items": {
              "type": "string",
              "format": "binary",  <= Added
              "contentMediaType": "application/octet-stream"
            },
            "type": "array",
            "title": "P"
          }
        },
        "type": "object",
        "required": [
          "p"
        ],
        "title": "Body_upload_files_uploadfile_upload_files_uploadfile_post"
      },
      "DataInput": {
        "properties": {
          "description": {
            "type": "string",
            "title": "Description"
          },
          "data": {
            "type": "string",  <= No 'format: binary' for JSON
            "contentMediaType": "application/octet-stream",
            "title": "Data"
          }
        },
        "type": "object",
        "required": [
          "description",
          "data"
        ],
        "title": "DataInput"
      },
      "DataInputBase64": {
        "properties": {
          "description": {
            "type": "string",
            "title": "Description"
          },
          "data": {
            "type": "string",  <= No 'format: binary' for JSON
            "contentEncoding": "base64",
            "contentMediaType": "application/octet-stream",
            "title": "Data"
          }
        },
        "type": "object",
        "required": [
          "description",
          "data"
        ],
        "title": "DataInputBase64"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    }
  }
}

All endpoints work in Swagger UI

…ry"`)

codspeed-hq · 2026-03-06T17:37:32Z

Merging this PR will not alter performance

✅ 20 untouched benchmarks

_{Comparing fix-multiple-upload-file-in-swagger (e5dbca9) with master (3969ae8)¹}

No successful run was found on master (ed7f49e) during the generation of this report, so 3969ae8 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

github-actions · 2026-03-15T11:51:06Z

This pull request has a merge conflict that needs to be resolved.

tiangolo · 2026-03-23T13:53:50Z

I was thinking we could just include the "format": "binary" the same way as before, have both there, I would hope that would simplify the logic. What do you think?

YuriiMotov · 2026-03-23T14:24:20Z

I was thinking we could just include the "format": "binary" the same way as before, have both there, I would hope that would simplify the logic. What do you think?

My bad, I didn't describe properly why we need to handle bytes inside JSON differently..

Specifying format: binary for bytes field inside JSON would be incorrect. In this case we should use format: byte (but we don't actually need to add it, so I omitted it).
See: https://spec.openapis.org/oas/v3.0.4.html#working-with-binary-data

kbumsik · 2026-04-13T08:14:05Z

Hi, will it be reviewed soon? I would like to contribute to this PR if more work is needed.

brainbytes42 · 2026-06-17T16:46:05Z

I ran into this issue having multiple files in my upload schema, but the docs having weird text input boxes. If I understand correctly, this PR should resolve it, but seems to be stale? Any chance to fix this issue, as the docs with ability to test the api are really great, if it works. Thanks! :-)

YuriiMotov · 2026-06-17T18:28:15Z

While we are waiting for the issue to be fixed, you can use workaround described here: #14975 (comment)

YuriiMotov added 2 commits March 6, 2026 11:08

Update schema for UploadFile (add format: binary)

506d278

Fix schema for byte fields inside JSON (do not add `"format": "bina…

3405306

…ry"`)

YuriiMotov added the bug Something isn't working label Mar 6, 2026

Fix typing issue

6aa2f98

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Mar 15, 2026

Merge branch 'master' into fix-multiple-upload-file-in-swagger

be926b4

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label Mar 16, 2026

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label May 11, 2026

This comment was marked as resolved.

Sign in to view

Merge branch 'master' into fix-multiple-upload-file-in-swagger

e5dbca9

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label May 20, 2026

hbrooks mentioned this pull request May 28, 2026

🦖 Fix multiple upload file schema to be compatible with OAS 3.0 to make it work in Swagger UI ellipsis-dev-test/fastapi#12

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

🦖 Fix multiple upload file schema to be compatible with OAS 3.0 to make it work in Swagger UI#15069

🦖 Fix multiple upload file schema to be compatible with OAS 3.0 to make it work in Swagger UI#15069
YuriiMotov wants to merge 5 commits into
masterfrom
fix-multiple-upload-file-in-swagger

YuriiMotov commented Mar 6, 2026 •

edited

Loading

Uh oh!

codspeed-hq Bot commented Mar 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 15, 2026

Uh oh!

tiangolo commented Mar 23, 2026

Uh oh!

YuriiMotov commented Mar 23, 2026 •

edited

Loading

Uh oh!

kbumsik commented Apr 13, 2026

Uh oh!

This comment was marked as resolved.

brainbytes42 commented Jun 17, 2026

Uh oh!

YuriiMotov commented Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Uh oh!

Conversation

YuriiMotov commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq Bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

github-actions Bot commented Mar 15, 2026

Uh oh!

tiangolo commented Mar 23, 2026

Uh oh!

YuriiMotov commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kbumsik commented Apr 13, 2026

Uh oh!

This comment was marked as resolved.

brainbytes42 commented Jun 17, 2026

Uh oh!

YuriiMotov commented Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

YuriiMotov commented Mar 6, 2026 •

edited

Loading

codspeed-hq Bot commented Mar 6, 2026 •

edited

Loading

YuriiMotov commented Mar 23, 2026 •

edited

Loading