Skip to content

Commit 99a193d

Browse files
authored
Correct formatting and wording in nullable annotations doc
1 parent b52b531 commit 99a193d

File tree

1 file changed

+8
-8
lines changed

1 file changed

+8
-8
lines changed

docs/standard/serialization/system-text-json/nullable-annotations.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -85,20 +85,20 @@ record MyPoco(
8585
);
8686
```
8787

88-
## Missing values vs. null values
88+
## Missing values versus null values
8989

90-
It's important to understand the distinction between missing JSON properties and properties with explicit `null` values when using <xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations>. JavaScript distinguishes between `undefined` (missing property) and `null` (explicit null value). However, .NET doesn't have an `undefined` concept, so both cases deserialize to `null` in .NET.
90+
It's important to understand the distinction between *missing JSON properties* and *properties with explicit `null` values* when you set <xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations>. JavaScript distinguishes between `undefined` (missing property) and `null` (explicit null value). However, .NET doesn't have an `undefined` concept, so both cases deserialize to `null` in .NET.
9191

92-
When `RespectNullableAnnotations` is `true`:
92+
During deserialization, when `RespectNullableAnnotations` is `true`:
9393

94-
- **Explicit null value**: Throws an exception for non-nullable properties. For example, `{"Name":null}` throws an exception when deserializing to a non-nullable `string Name` property.
95-
- **Missing property**: Does NOT throw an exception, even for non-nullable properties. For example, `{}` does not throw an exception when deserializing to a non-nullable `string Name` property. The property is set to `null`.
94+
- An **explicit null value** throws an exception for non-nullable properties. For example, `{"Name":null}` throws an exception when deserializing to a non-nullable `string Name` property.
95+
- A **missing property** doesn't throw an exception, even for non-nullable properties. For example, `{}` doesn't throw an exception when deserializing to a non-nullable `string Name` property. The property is set to `null`.
9696

97-
The following code demonstrates this difference:
97+
The following code shows how a missing property does NOT throw an exception during deserialization:
9898

99-
:::code language="csharp" source="snippets/nullable-annotations/Nullable.cs" id="MissingVsNull":::
99+
:::code language="csharp" source="snippets/nullable-annotations/Nullable.cs" id="MissingVsNull":::
100100

101-
This behavior occurs because missing properties are treated as optional (not provided), while explicit `null` values are treated as provided values that violate the non-nullable constraint. If you need to enforce that a property must be present in the JSON, use the `required` modifier or configure the property as required using <xref:System.Text.Json.Serialization.JsonRequiredAttribute> or the contracts model.
101+
This behavior difference occurs because missing properties are treated as optional (not provided), while explicit `null` values are treated as provided values that violate the non-nullable constraint. If you need to enforce that a property must be present in the JSON, use the `required` modifier or configure the property as required using <xref:System.Text.Json.Serialization.JsonRequiredAttribute> or the contracts model.
102102

103103
## See also
104104

0 commit comments

Comments
 (0)