Skip to content

📝 Clarify required but nullable request body fields#14751

Closed
azamzar wants to merge 12 commits intofastapi:masterfrom
azamzar:docs-required-nullable-clean
Closed

📝 Clarify required but nullable request body fields#14751
azamzar wants to merge 12 commits intofastapi:masterfrom
azamzar:docs-required-nullable-clean

Conversation

@azamzar
Copy link
Copy Markdown

@azamzar azamzar commented Jan 21, 2026

This PR clarifies how request body fields can be required while still allowing null (None) values when using Optional[T] without a default.

Changes included:

  • Added a new subsection "Required fields that can be None" under the Request Body tutorial.
  • Included a minimal, working Python example showing a field that is required but nullable.
  • Explained the difference between required-but-nullable fields and truly optional fields with a default value.

This is a documentation-only change; no runtime or API behavior is affected.

@github-actions github-actions Bot added the docs Documentation about how to use FastAPI label Jan 21, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jan 21, 2026 •
edited
Loading

📝 Docs preview

Last commit 2682f7d at: https://e9874f20.fastapitiangolo.pages.dev

Modified Pages

@codspeed-hq
Copy link
Copy Markdown

codspeed-hq Bot commented Jan 21, 2026 •
edited
Loading

Merging this PR will not alter performance

✅ 20 untouched benchmarks

Comparing azamzar:docs-required-nullable-clean (2682f7d) with master (b93c964)1

Open in CodSpeed

Footnotes

  1. No successful run was found on master (5420847) during the generation of this report, so b93c964 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

@azamzar azamzar force-pushed the docs-required-nullable-clean branch 2 times, most recently from 8a19a81 to fa6af8b Compare January 21, 2026 12:50
@azamzar
Copy link
Copy Markdown
Author

azamzar commented Jan 21, 2026

This PR complements #14653 by providing an alternative explanation and example for required but nullable request body fields.

  • Adds a minimal working Python example demonstrating the difference between:
    • Required but nullable fields (Optional[T] without a default)
    • Truly optional fields with a default value (Optional[T] = None)
  • Clarifies that required fields can still have a null value in requests.
  • Documentation-only change; no runtime or API behavior is affected.

This is intended to enhance the explanation already started in #14653 and provide additional clarity for readers.

Happy to collaborate and merge the best parts with #14653 if the maintainers prefer.

YuriiMotov
YuriiMotov reviewed Jan 21, 2026
View reviewed changes
Comment thread docs/en/docs/tutorial/body.md Outdated
Comment on lines +68 to +81
```python
from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
description: Optional[str]

@app.post("/items/")
async def create_item(item: Item):
return item
```
Copy link
Copy Markdown
Member

@YuriiMotov YuriiMotov Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All code examples should be placed in separate files and covered by tests.
Please, look how it's done for other code examples in docs

Copy link
Copy Markdown
Author

@azamzar azamzar Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback!
I’ve moved the example to separate numbered tutorial files under docs_src/body (for Python 3.9 and 3.10+), added tests following the existing pattern, and updated the documentation to reference them.

Copy link
Copy Markdown
Author

@azamzar azamzar Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @YuriiMotov ! Just a gentle ping in case this PR got buried.
All checks are green now — happy to adjust anything if needed. Thanks!

@azamzar azamzar force-pushed the docs-required-nullable-clean branch 6 times, most recently from f12a2bb to a6196a3 Compare January 22, 2026 12:18
@azamzar azamzar force-pushed the docs-required-nullable-clean branch from 91469e0 to eec2fe9 Compare January 22, 2026 12:23
@alejsdev alejsdev changed the title docs: clarify required but nullable request body fields 📝 Clarify required but nullable request body fields Feb 10, 2026
YuriiMotov
YuriiMotov requested changes Feb 13, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@YuriiMotov YuriiMotov left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@azamzar, thanks!

In addition to code review comments, the test file should be named test_tutorial005.py and placed in tests/test_tutorial/test_body

Comment thread docs/en/docs/tutorial/body.md Outdated
Comment thread docs/en/docs/tutorial/body.md Outdated
Comment thread docs/en/docs/tutorial/body.md Outdated
Comment thread docs_src/body/tutorial005_py39.py Outdated
Comment thread tests/test_tutorial/test_body_required_nullable/test_tutorial001.py Outdated
Comment thread tests/test_tutorial/test_body_required_nullable/test_tutorial001.py Outdated
@azamzar
Copy link
Copy Markdown
Author

azamzar commented Feb 13, 2026

Hi @YuriiMotov, the requested changes have been implemented and all tests are passing. Please take another look. Thanks!

@azamzar azamzar requested a review from YuriiMotov February 13, 2026 17:25
YuriiMotov
YuriiMotov reviewed Feb 13, 2026
View reviewed changes
Comment thread docs_src/body/tutorial005_py310.py Outdated
@YuriiMotov
Copy link
Copy Markdown
Member

YuriiMotov commented Feb 13, 2026

Please, review carefully before asking others for review

@azamzar
Copy link
Copy Markdown
Author

azamzar commented Feb 13, 2026

@YuriiMotov The requested changes have been applied: the description field is now required as intended.
All related tests are passing now. Please review when you have a moment. Thanks!

@azamzar azamzar requested a review from YuriiMotov February 13, 2026 18:22
@tiangolo
Copy link
Copy Markdown
Member

tiangolo commented Feb 15, 2026

Thanks for the interest, but this is already explained in a different point in the tutorial, I don't think it's necessary to explain it here too. I'll pass on this for now, thanks! ☕

@tiangolo tiangolo closed this Feb 15, 2026
@azamzar
Copy link
Copy Markdown
Author

azamzar commented Feb 17, 2026

Thanks for the interest, but this is already explained in a different point in the tutorial, I don't think it's necessary to explain it here too. I'll pass on this for now, thanks! ☕

Thanks for the clarification! That makes sense.
Appreciate the review and your time 🙂

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@YuriiMotov YuriiMotov Awaiting requested review from YuriiMotov

Assignees

No one assigned

Labels

docs Documentation about how to use FastAPI

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@azamzar @YuriiMotov @tiangolo