From eeaa478527e22d4059cf6d465d51597229d90175 Mon Sep 17 00:00:00 2001 From: naveencreation Date: Thu, 19 Mar 2026 11:09:36 +0530 Subject: [PATCH] Clarify required but nullable query parameters behavior --- .../tutorial/query-params-str-validations.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md index 4765b36cbe..b8748d9588 100644 --- a/docs/en/docs/tutorial/query-params-str-validations.md +++ b/docs/en/docs/tutorial/query-params-str-validations.md @@ -228,6 +228,41 @@ To do that, you can declare that `None` is a valid type but simply do not declar {* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *} +#### Important: Query parameters are always strings + +Even though you can declare a parameter as "required but can be `None`", in practice, query parameters are always received as strings in HTTP. + +For example: + +``` +/items?q=null +``` + +This will be interpreted as `"null"` (a string), **not** `None`. + +#### Recommendation + +Because query parameters cannot truly represent `None`, this pattern can be confusing in real-world usage. + +In most cases, it is better to: + +- Make the parameter optional: + +```python +q: Annotated[str | None, Query(min_length=3)] = None +``` + +- Or use a request body if you need to explicitly support `None` + +#### Summary + +| Declaration | Behavior | +| ----------- | -------- | +| `q: str` | required | +| `q: str = None` | optional | +| `q: str \| None = None` | optional nullable | +| `q: str \| None = ...` | required but not practical in query params | + ## Query parameter list / multiple values { #query-parameter-list-multiple-values } When you define a query parameter explicitly with `Query` you can also declare it to receive a list of values, or said in another way, to receive multiple values.