From 226e064009f060fd9c9d395c18eef4cccb45aa5d Mon Sep 17 00:00:00 2001
From: Varun Chawla <varun_6april@hotmail.com>
Date: Sat, 7 Feb 2026 18:07:25 -0800
Subject: [PATCH] Clarify documentation for required query params with None
 type

Fixes #12419

**Problem:**
The documentation section "Required, can be None" was misleading. It suggested
that you could force clients to send a None value, but HTTP query parameters
cannot send literal None - they're either strings or omitted entirely.

The example showed `q: Annotated[str | None, Query(min_length=3)]` without a
default value, which makes the parameter required. However, there's no way for
a client to satisfy this by sending None via HTTP query parameters.

**Solution:**
Updated the documentation to:
1. Rename the section to "Required with None type" to be more accurate
2. Add a detailed note explaining HTTP query parameter limitations
3. Clarify that omitting the parameter results in a validation error
4. Explain this pattern is more useful for dependencies than HTTP endpoints
5. Show the correct pattern for optional parameters that can be omitted

**Testing:**
The existing tests in test_tutorial006c.py are already marked as xfail with a
reference to this issue, confirming the example doesn't work as described. This
documentation update clarifies the behavior instead of changing the example to
something that would work differently.

This helps developers understand when to use this pattern (dependencies) vs
when to use optional parameters with defaults (HTTP endpoints).
---
 .../tutorial/query-params-str-validations.md  | 20 +++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md
index 4b8cc9d29..6839ebdb5 100644
--- a/docs/en/docs/tutorial/query-params-str-validations.md
+++ b/docs/en/docs/tutorial/query-params-str-validations.md
@@ -244,14 +244,26 @@ So, when you need to declare a value as required while using `Query`, you can si
 
 {* ../../docs_src/query_params_str_validations/tutorial006_an_py39.py hl[9] *}
 
-### Required, can be `None` { #required-can-be-none }
+### Required with `None` type { #required-can-be-none }
 
-You can declare that a parameter can accept `None`, but that it's still required. This would force clients to send a value, even if the value is `None`.
-
-To do that, you can declare that `None` is a valid type but simply do not declare a default value:
+You can declare that a parameter has a type that includes `None` (like `str | None`) but without a default value, which makes it required:
 
 {* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
 
+/// note
+
+**Important**: Even though the type includes `None`, the parameter is still **required** because there's no default value. This means clients **must** provide the parameter.
+
+In practice, HTTP query parameters are sent as strings. While the type annotation `str | None` indicates the parameter could theoretically be `None`, there's no standard way to send a literal `None` value in HTTP query parameters - you can only send string values or omit the parameter entirely.
+
+**Omitting the parameter will result in a validation error** since it's required.
+
+This pattern is more commonly useful for **dependencies** (where you might pass `None` programmatically) rather than direct HTTP endpoints.
+
+For an optional query parameter that can be omitted, use: `q: Annotated[str | None, Query(min_length=3)] = None`
+
+///
+
 ## 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.