📝 Clarify misleading "Required, can be `None`" section in `query-params-str-validations.md` #14322

ChaitanyaSai-Meka · 2025-11-10T05:05:45Z

The previous explanation suggested that a query parameter could be both required and accept a true None value.
However, since HTTP query parameters are transmitted as strings, clients cannot actually send None or null.

This update clarifies that behavior and adds an example showing how to manually handle "None" or empty strings as None inside a route.

ChaitanyaSai-Meka · 2025-11-10T05:08:32Z

Hi 👋,
This PR clarifies a small inaccuracy in the “Required, can be None” section of the Query Params tutorial.
It explains that query parameters can’t actually carry None and adds a short example showing how to handle special values like "None" or an empty string.

This is my first contribution to FastAPI 🎉 — really excited to start contributing to the project!

github-actions · 2025-11-10T05:09:08Z

📝 Docs preview

Last commit 9f6fe4a at: https://774bf08f.fastapitiangolo.pages.dev

Modified Pages

https://774bf08f.fastapitiangolo.pages.dev/tutorial/query-params-str-validations/ - (before)

docs_src/query_params_str_validations/tutorial006d_an_py310.py

tests/test_tutorial/test_query_params_str_validations/test_tutorial006d_an_py310.py

YuriiMotov

LGTM!

@ChaitanyaSai-Meka, thanks!

docs/en/docs/tutorial/query-params-str-validations.md

ChaitanyaSai-Meka · 2025-11-11T11:20:37Z

Thanks @YuriiMotov! Really appreciate your review and guidance 🙌
Glad to have contributed to FastAPI!

docs/en/docs/tutorial/query-params-str-validations.md

…am validation

… can be None section

…lity

Copilot

Pull request overview

This pull request clarifies misleading documentation about using "required" query parameters that can accept None values. The previous documentation incorrectly suggested that FastAPI could handle a truly required parameter that also accepts a real None value, but HTTP query parameters are always transmitted as strings, making this impossible.

Key Changes:

Updated documentation to explain that HTTP query parameters cannot send real None values
Added example demonstrating how to manually interpret string values like "None" or empty strings as None using Pydantic's BeforeValidator
Removed old non-annotated example files and updated tests to match the new validator-based approach

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/en/docs/tutorial/query-params-str-validations.md	Rewrote "Required, can be `None`" section to clarify HTTP limitations and show validator workaround
docs_src/query_params_str_validations/tutorial006c_py39.py	Deleted - replaced with annotated version using BeforeValidator
docs_src/query_params_str_validations/tutorial006c_py310.py	Deleted - replaced with annotated version using BeforeValidator
docs_src/query_params_str_validations/tutorial006c_an_py39.py	Added `nullable_str` validator function and BeforeValidator to handle None-like strings
docs_src/query_params_str_validations/tutorial006c_an_py310.py	Added `nullable_str` validator function and BeforeValidator to handle None-like strings
tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py	Removed references to deleted files, updated tests to verify 422 on missing param and 200 on None-like strings

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py

github-actions bot added the docs Documentation about how to use FastAPI label Nov 10, 2025

This comment was marked as resolved.

Sign in to view

YuriiMotov changed the title ~~Clarify misleading “Required, can be None” section in query parameter validation~~ 📝 Clarify misleading "Required, can be None" section in query-params-str-validations.md Nov 10, 2025

ChaitanyaSai-Meka force-pushed the docs/fix-required-can-be-none branch from 18ccbd1 to f873cb9 Compare November 10, 2025 09:44

This comment was marked as resolved.

Sign in to view

ChaitanyaSai-Meka force-pushed the docs/fix-required-can-be-none branch 2 times, most recently from 9021a4b to 3259949 Compare November 10, 2025 10:00

This comment was marked as resolved.

Sign in to view

ChaitanyaSai-Meka force-pushed the docs/fix-required-can-be-none branch from 5a446c9 to bb64c97 Compare November 10, 2025 10:16

This comment was marked as resolved.

Sign in to view

ChaitanyaSai-Meka requested a review from YuriiMotov November 10, 2025 10:33

YuriiMotov reviewed Nov 10, 2025

View reviewed changes

docs_src/query_params_str_validations/tutorial006d_an_py310.py Outdated Show resolved Hide resolved

YuriiMotov reviewed Nov 10, 2025

View reviewed changes

tests/test_tutorial/test_query_params_str_validations/test_tutorial006d_an_py310.py Outdated Show resolved Hide resolved

ChaitanyaSai-Meka requested a review from YuriiMotov November 10, 2025 10:58

YuriiMotov mentioned this pull request Nov 10, 2025

docs: clarify required query param that can be None #14250

Closed

This comment was marked as resolved.

Sign in to view

YuriiMotov approved these changes Nov 11, 2025

View reviewed changes

docs/en/docs/tutorial/query-params-str-validations.md Outdated Show resolved Hide resolved

docs/en/docs/tutorial/query-params-str-validations.md Outdated Show resolved Hide resolved

YuriiMotov reviewed Nov 11, 2025

View reviewed changes

docs/en/docs/tutorial/query-params-str-validations.md Outdated Show resolved Hide resolved

YuriiMotov reviewed Nov 11, 2025

View reviewed changes

docs/en/docs/tutorial/query-params-str-validations.md Outdated Show resolved Hide resolved

This comment was marked as resolved.

Sign in to view

github-actions bot added the conflicts Automatically generated when a PR has a merge conflict label Dec 16, 2025

This comment was marked as resolved.

Sign in to view

YuriiMotov linked an issue Dec 18, 2025 that may be closed by this pull request

Question about "Required, can be None" parameter #12419

Open

9 tasks

YuriiMotov mentioned this pull request Dec 19, 2025

✅ Add missing tests for code examples #14569

Merged

ChaitanyaSai-Meka and others added 15 commits January 8, 2026 12:05

docs: clarify misleading 'Required, can be None' section in query par…

882fa91

…am validation

docs: fix inline code formatting and add tested example for Required,…

6eb3484

… can be None section

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

a28557e

docs: finalize Required, can be None example with test verification

9b8beb4

style: clean formatting with Ruff + Black

f991cce

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

d240ac8

fix: import Annotated from typing_extensions for Python 3.8 compatibi…

6c021d2

…lity

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

05f7999

test: finalize client fixture and absolute import for needs_pydanticv2

b960384

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

909d174

docs: clarify BeforeValidator is available only in Pydantic v2

79ba18b

Apply suggestions from code review

67c8518

Update docs/en/docs/tutorial/query-params-str-validations.md

d377cbf

Update highlights

98bc4db

Rename code example file and add variants

1a4cdb3

Copilot AI review requested due to automatic review settings January 8, 2026 11:30

YuriiMotov force-pushed the docs/fix-required-can-be-none branch from 03ca4c1 to 1a4cdb3 Compare January 8, 2026 11:30

github-actions bot removed the conflicts Automatically generated when a PR has a merge conflict label Jan 8, 2026

Copilot started reviewing on behalf of YuriiMotov January 8, 2026 11:30 View session

🎨 Auto format

1de6fc1

This comment was marked as resolved.

Sign in to view

Copilot AI reviewed Jan 8, 2026

View reviewed changes

tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py Show resolved Hide resolved

Update text in docs

9f6fe4a

YuriiMotov mentioned this pull request Jan 9, 2026

Clarify "Required, can be None" section in query params docs #14670

Closed

Uh oh!

📝 Clarify misleading "Required, can be None" section in query-params-str-validations.md #14322

Are you sure you want to change the base?

📝 Clarify misleading "Required, can be None" section in query-params-str-validations.md #14322

Conversation

ChaitanyaSai-Meka commented Nov 10, 2025

Uh oh!

ChaitanyaSai-Meka commented Nov 10, 2025

Uh oh!

github-actions bot commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Docs preview

Modified Pages

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

YuriiMotov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ChaitanyaSai-Meka commented Nov 11, 2025

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

📝 Clarify misleading "Required, can be `None`" section in `query-params-str-validations.md` #14322

📝 Clarify misleading "Required, can be `None`" section in `query-params-str-validations.md` #14322

github-actions bot commented Nov 10, 2025 •

edited

Loading