How to accept an optional datetime query parameter which is explicitly provided as null?

[maxispeicher]

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 Annotated

import uvicorn
from fastapi import FastAPI, Query
from datetime import datetime


app = FastAPI()


@app.get("/")
def root(dt: Annotated[datetime | None, Query(description="I want to be able to provide `null` for this.")] = None):
    return dt


if __name__ == "__main__":
    uvicorn.run("main:app", host="127.0.0.1", reload=True)

Description

• http://127.0.0.1:8000/ returns null as expected
• http://127.0.0.1:8000/?dt=2020-12-30 returns "2020-12-30T00:00:00" as expected
• http://127.0.0.1:8000/?dt=null returns { "detail": [ { "type": "datetime_from_date_parsing", "loc": [ "query", "dt" ], "msg": "Input should be a valid datetime or date, input is too short", "input": "null", "ctx": { "error": "input is too short" } } ] } instead of null

Operating System

Linux

Operating System Details

No response

FastAPI Version

0.110.2

Pydantic Version

2.7.1

Python Version

Python 3.11.6

Additional Context

No response

[angely-dev]

What about using an Enum?

from typing import Annotated
from enum import Enum
import uvicorn
from fastapi import FastAPI, Query
from datetime import datetime


app = FastAPI()

class DtEnum(str, Enum):
    null = "null"

@app.get("/")
def root(dt: Annotated[datetime | DtEnum | None, Query(description="...")] = None):
    if not dt or dt == DtEnum.null:
        return None
    return dt

Test:

• http://localhost:8000/ returns null
• http://localhost:8000/?dt=null returns null
• http://localhost:8000/?dt=2020-12-30 returns "2020-12-30T00:00:00"
• http://localhost:8000/?dt=abc triggers a validation error

[YuriiMotov]

null in the http://127.0.0.1:8000/?dt=null reuest is not an empty value, but a string "null". So, if you want to let clients send this type of requests, you should include it in type annotation.
I think you can either use the approach with enum that is shown above, or you can use Literal['null']:

def root(dt: Annotated[datetime | None | Literal['null'], Query(description="I want to be able to provide `null` for this.")] = None):

You can also exlude this null from schema by using SkipJsonSchema:

def root(dt: Annotated[datetime | None | SkipJsonSchema[Literal['null']], Query(description="I want to be able to provide `null` for this.")] = None):

And by including Literal[''] you can also support requests like http://127.0.0.1:8000/?dt=.

Final annotation that works as you expected (as I understand what you want), but without all these "null" and "" in json schema:

def root(dt: Annotated[datetime | SkipJsonSchema[Literal['null']] | SkipJsonSchema[Literal['']] | SkipJsonSchema[None], Query(description="You can either skip this parameter, or pass an empty value or 'null', as well as a correct DateTime value")] = None):

I don't know whether there is a nicer way to do that..

[maxispeicher]

Thank you both for your answers, I also agree that it's a little bit strange to do it at all. I was just wondering as this exactly what is for example produced by requests if you do a request with a parameter set to None.