From f23cd4f095676af2d17681ab447fb014802dd869 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Wed, 21 Oct 2026 11:34:12 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Clarify=20boolean=20query=20para?=
 =?UTF-8?q?meter=20parsing=20(#16569)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/en/docs/tutorial/query-params.md         |  8 +++++-
 .../test_query_params/test_tutorial003.py     | 26 +++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/docs/en/docs/tutorial/query-params.md b/docs/en/docs/tutorial/query-params.md
index cb89e23e7a..a744952419 100644
--- a/docs/en/docs/tutorial/query-params.md
+++ b/docs/en/docs/tutorial/query-params.md
@@ -107,7 +107,13 @@ or
 http://127.0.0.1:8000/items/foo?short=yes
 ```
 
-or any other case variation (uppercase, first letter in uppercase, etc), your function will see the parameter `short` with a `bool` value of `True`. Otherwise as `False`.
+or any other case variation (uppercase, first letter in uppercase, etc), your function will see the parameter `short` with a `bool` value of `True`.
+
+Values such as `0`, `false`, `off`, and `no` (including case variations) are converted to `False`.
+
+If `short` is omitted, **FastAPI** uses its default value, which is `False` in this example.
+
+An empty value (`?short=`) or an unrecognized value (for example, `?short=maybe`) produces a `422` validation error.
 
 
 ## Multiple path and query parameters { #multiple-path-and-query-parameters }
diff --git a/tests/test_tutorial/test_query_params/test_tutorial003.py b/tests/test_tutorial/test_query_params/test_tutorial003.py
index 2951f1adf9..151abef2cb 100644
--- a/tests/test_tutorial/test_query_params/test_tutorial003.py
+++ b/tests/test_tutorial/test_query_params/test_tutorial003.py
@@ -50,6 +50,32 @@ def test_read_user_item(client: TestClient, path, expected_json):
     assert response.json() == expected_json
 
 
+@pytest.mark.parametrize("short", ["0", "false", "off", "no", "FaLsE"])
+def test_boolean_query_false(client: TestClient, short: str):
+    response = client.get("/items/foo", params={"short": short})
+    assert response.status_code == 200
+    assert response.json() == {
+        "item_id": "foo",
+        "description": "This is an amazing item that has a long description",
+    }
+
+
+@pytest.mark.parametrize("short", ["", "maybe"])
+def test_invalid_boolean_query(client: TestClient, short: str):
+    response = client.get("/items/foo", params={"short": short})
+    assert response.status_code == 422
+    assert response.json() == {
+        "detail": [
+            {
+                "type": "bool_parsing",
+                "loc": ["query", "short"],
+                "msg": "Input should be a valid boolean, unable to interpret input",
+                "input": short,
+            }
+        ]
+    }
+
+
 def test_openapi_schema(client: TestClient):
     response = client.get("/openapi.json")
     assert response.status_code == 200