Document missing vs. null value behavior in RespectNullableAnnotations

[Copilot]

• Review the current nullable-annotations.md documentation
• Understand the difference between missing/undefined values and null values in JSON deserialization
• Add a new section explaining that missing (undefined) JSON values are treated differently from null values
• Create code examples demonstrating the behavior with missing values vs null values
• Update the snippets to include examples showing missing values
• Build and validate the code snippets compile correctly
• Review and ensure the documentation follows writing style guidelines
• Address reviewer feedback about missing properties being left at default values rather than set to null
• Final verification of all changes

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Deserialization with RespectNullableAnnotations = true does not treat undefined as null</issue_title>
<issue_description>### Type of issue

Missing information

Description

JavaScript distinguishes between null and undefined and when JSON is deserialized a missing value becomes undefined. However, undefined does not exist in .NET and a missing string or object value deserializes to .NET null. This can lead to confusion when setting RespectNullableAnnotations to true because if the JSON value is missing, no exception is thrown when the target property is non-nullable leading to the property being null despite the setting. I think this article could be improved by explaining this.

Even better, it would be nice if JSON deserialization could be configured to treat a missing value the same way as null when deserializing to a non-null string or object. 🙏 Yes, I know this is not a documentation issue, but I had to mention it. 😀

Page URL

https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/nullable-annotations

Content source URL

https://github.com/dotnet/docs/blob/main/docs/standard/serialization/system-text-json/nullable-annotations.md

Document Version Independent Id

7ae3d826-764a-2c29-a251-1a237beedd1a

Platform Id

5aacc351-ddac-0ce8-57df-aabac452d55b

Article author

@gewarren

Metadata

• ID: 44d16e49-e10a-92b0-147e-a46542aefd51
• PlatformId: 5aacc351-ddac-0ce8-57df-aabac452d55b
• Service: dotnet-fundamentals

Related Issues</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #49298

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

---

Internal previews

📄 File	🔗 Preview link
docs/standard/serialization/system-text-json/nullable-annotations.md	Respect nullable annotations

[gewarren]

I verified the code works as advertised.

[Copilot]

Pull Request Overview

This PR addresses a documentation gap by clarifying how RespectNullableAnnotations behaves differently when JSON properties are missing versus explicitly set to null. The documentation update explains that JavaScript's undefined (missing property) and null (explicit null value) both deserialize to .NET null, but only explicit null values trigger exceptions for non-nullable properties.

Key Changes:

• Added a new "Missing values versus null values" section explaining the behavioral distinction
• Created a code example demonstrating that missing properties don't throw exceptions
• Updated metadata (date and added ai-usage frontmatter)

Reviewed Changes

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

File	Description
nullable-annotations.md	Added new section documenting missing vs. null value behavior and enforcement guidance
Nullable.cs	Added Nullable4 class with MissingVsNull example demonstrating missing property behavior
Program.cs	Updated to run the new Nullable4 example

[wadepickett]

Looks good to me. I am not finding an issue. Well written, great code example. Approved. Policheck seems to be slow or held up?

[tdykstra]

Looks good!