Treat null same as missing value for Optional query and form params

[axd1x8a]

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 Optional
from uuid import UUID

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/")
async def nullable_param(param: Optional[UUID] = Form(None)):
    return {"param": param}

Description

Request with empty value or without param will work as expected and return {"param": null}

But request with param=null will fail:

{
  "detail": [
    {
      "type": "uuid_parsing",
      "loc": [
        "body",
        "param"
      ],
      "msg": "Input should be a valid UUID, invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-fA-F-], found `n` at 1",
      "input": "null",
      "ctx": {
        "error": "invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-fA-F-], found `n` at 1"
      },
      "url": "https://errors.pydantic.dev/2.4/v/uuid_parsing"
    }
  ]
}

same for query params

Operating System

Other

Operating System Details

No response

FastAPI Version

0.104.1

Pydantic Version

2.4.2

Python Version

Python 3.11.1

Additional Context

No response

[Painkiller995]

I'm having the same issue here.

[sinisaos]

@Painkiller995 Sorry if I misunderstood the request, but you can use Union type to make all options work. Something like this

from fastapi import FastAPI, Form
from typing import Union
from uuid import UUID


app = FastAPI()


@app.post("/")
async def nullable_param(param: Union[UUID, str] = Form(None)):
    return {"param": param}

The result is

> curl --form param=3fa85f64-5717-4562-b3fc-2c963f66afa6 http://127.0.0.1:8000
{"param":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}
> curl --form param= http://127.0.0.1:8000
{"param":""}
> curl --form param=null http://127.0.0.1:8000
{"param":"null"}

Same result is in the Swagger UI.

[mattmess1221]

Remember not to confuse "null" the string with null the json value.

[sinisaos]

@killjoy1221 Sorry if I didn't understand the request well. Should a null as a string in a param be treated as an empty value and rendered as json null? If so, we can use pydantic validator because in the latest version of FastAPI we can use Pydantic model in forms. Something like this

from fastapi import FastAPI, Form
from pydantic import BaseModel, field_validator
from typing import Union, Annotated, Optional
from uuid import UUID


class FormData(BaseModel):
    data: Union[UUID, str] = None

    @field_validator("data")
    @classmethod
    def empty_or_null_to_none(cls, v: str) -> Optional[str]:
        if v == "" or v == "null":
            return None
        return v


app = FastAPI()


@app.post("/")
async def nullable_param(param: Annotated[FormData, Form()]):
    return {"param": param.data}

Result is same using curl or Swagger UI

> curl --form data=3fa85f64-5717-4562-b3fc-2c963f66afa6 http://127.0.0.1:8000
{"param":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}
> curl --form data= http://127.0.0.1:8000
{"param":null}
> curl --form data=null http://127.0.0.1:8000
{"param":null} <- like this

[YuriiMotov]

When you send param=null it's treated as string "null".

To send empty value you should either omit this parameter:

curl -X POST http://127.0.0.1:8000

Or send empty value (browsers do this):

curl -X POST http://127.0.0.1:8000 -F param=

But in current version the second request (with param=) will lead to validation error. FastAPI treats it as empty string.
To solve this you can use BeforeValidator that will convert empty string to None.
You also need to use SkipJsonSchema to make it working correctly in Swagger UI.

So, working solution:

from typing import Annotated
from uuid import UUID

from fastapi import FastAPI, Form
from pydantic import BeforeValidator
from pydantic.json_schema import SkipJsonSchema

app = FastAPI()


@app.post("/")
async def nullable_param(
    param: Annotated[
        UUID | SkipJsonSchema[None],
        Form(),
        BeforeValidator(lambda v: v or None),
    ] = None,
):
    return {"param": param}

[axd1x8a]

Now it looks even more like a FastAPI's issue. Validators can solve this, but it should be handled by FastAPI itself, otherwise what's the point of using it?
Also now I wonder what the specification says about null values in query params