respect nullable annotations

Author: gewarren

docs/core/whats-new/dotnet-9/libraries.md

@@ -499,22 +499,11 @@ For more information, see [JSON schema exporter](../../../standard/serialization
 
 <xref:System.Text.Json> now recognizes nullability annotations of properties and can be configured to enforce those during serialization and deserialization using the <xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations> flag.
 
-The following code shows how to set the option (the `Book` type definition is shown in the previous section):
+The following code shows how to set the option:
 
 :::code language="csharp" source="../snippets/dotnet-9/csharp/Serialization.cs" id="RespectNullable":::
 
-> [!NOTE]
-> Due to how nullability annotations are represented in IL, the feature is restricted to annotations of non-generic properties.
-
-You can also enable this setting globally using the `System.Text.Json.Serialization.RespectNullableAnnotationsDefault` feature switch in your project file (for example, _.csproj_ file):
-
-```xml
-<ItemGroup>
-  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectNullableAnnotationsDefault" Value="true" />
-</ItemGroup>
-```
-
-You can configure nullability at an individual property level using the <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsGetNullable> and <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsSetNullable> properties.
+For more information, see [Respect nullable annotations](../../../standard/serialization/system-text-json/nullable-annotations.md).
 
 ### Require non-optional constructor parameters
 

docs/core/whats-new/snippets/dotnet-9/csharp/Serialization.cs

@@ -64,23 +64,6 @@ public static void RunIt()
         // </PropertyOrder>
     }
 
-    public static void RunIt2()
-    {
-        // <RespectNullable>
-        JsonSerializerOptions options = new() { RespectNullableAnnotations = true };
-
-        // Throws exception: System.Text.Json.JsonException: The property or field
-        // 'Title' on type 'Serialization+Book' doesn't allow getting null values.
-        // Consider updating its nullability annotation.
-        JsonSerializer.Serialize(new Book { Title = null! }, options);
-
-        // Throws exception: System.Text.Json.JsonException: The property or field
-        // 'Title' on type 'Serialization+Book' doesn't allow setting null values.
-        // Consider updating its nullability annotation. 
-        JsonSerializer.Deserialize<Book>("""{ "Title" : null }""", options);
-        // </RespectNullable>
-    }
-
     public static void RunIt3()
     {
         // <RespectRequired>
@@ -105,3 +88,30 @@ public class Book
     record MyPoco(string Value);
     // </Poco>
 }
+
+public static class Serialization2
+{
+    // <RespectNullable>
+    public static void RunIt()
+    {
+        JsonSerializerOptions options = new() { RespectNullableAnnotations = true };
+
+        // Throws exception: System.Text.Json.JsonException: The property or field
+        // 'Title' on type 'Serialization+Book' doesn't allow getting null values.
+        // Consider updating its nullability annotation.
+        JsonSerializer.Serialize(new Book { Title = null! }, options);
+
+        // Throws exception: System.Text.Json.JsonException: The property or field
+        // 'Title' on type 'Serialization+Book' doesn't allow setting null values.
+        // Consider updating its nullability annotation.
+        JsonSerializer.Deserialize<Book>("""{ "Title" : null }""", options);
+    }
+
+    public class Book
+    {
+        public required string Title { get; set; }
+        public string? Author { get; set; }
+        public int PublishYear { get; set; }
+    }
+    // </RespectNullable>
+}

docs/fundamentals/toc.yml

@@ -737,6 +737,8 @@ items:
                         href: ../standard/serialization/system-text-json/deserialization.md
                       - name: Require JSON properties
                         href: ../standard/serialization/system-text-json/required-properties.md
+                      - name: Respect nullable annotations
+                        href: ../standard/serialization/system-text-json/nullable-annotations.md
                       - name: Allow invalid JSON
                         href: ../standard/serialization/system-text-json/invalid-json.md
                       - name: Handle missing members

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

@@ -0,0 +1,86 @@
+---
+title: Respect nullable annotations
+description: "Learn how to configure serialization and deserialization to respect nullable annotations."
+ms.date: 10/22/2024
+no-loc: [System.Text.Json, Newtonsoft.Json]
+---
+# Respect nullable annotations
+
+Starting in .NET 9, <xref:System.Text.Json.JsonSerializer> has (limited) support for non-nullable reference type enforcement in both serialization and deserialization. You can toggle this support using the <xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations?displayProperty=nameWithType> flag.
+
+For example, the following code snippet throws a <xref:System.Text.Json.JsonException> during serialization with a message like:
+
+> The property or field 'Name' on type 'Person' doesn't allow getting null values. Consider updating its nullability annotation.
+
+:::code language="csharp" source="snippets/nullable-annotations/Nullable.cs" id="Serialization":::
+
+Similarly, <xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations> enforces nullability on deserialization. The following code snippet throws a <xref:System.Text.Json.JsonException> during serialization with a message like:
+
+> The constructor parameter 'Name' on type 'Person' doesn't allow null values. Consider updating its nullability annotation.
+
+:::code language="csharp" source="snippets/nullable-annotations/Nullable.cs" id="Deserialization":::
+
+> [!TIP]
+> You can configure nullability at an individual property level using the <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsGetNullable> and <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsSetNullable> properties.
+
+## Limitations
+
+Due to how non-nullable reference types are implemented, this feature comes with some important limitations. Familiarize yourself with these limitations before turning the feature on. The root of the issue is that reference type nullability has no first-class representation in intermediate language (IL). As such, the expressions `MyPoco` and `MyPoco?` are indistinguishable from the perspective of run-time reflection. While the compiler will try to make up for that by [emitting attribute metadata where possible](https://sharplab.io/#v2:D4AQTAjAsAULBOBTAxge3gEwAQFkCeACqmgBQgQAMWAcqgC7UCuANswMp3wCWAdgOYAaLOQoB+Gi2YBDAEbNEHbvwCUAbiA=), this metadata is restricted to non-generic member annotations that are scoped to a particular type definition. This is the reason that the flag only validates nullability annotations that are present on non-generic properties, fields, and constructor parameters. System.Text.Json does not support nullability enforcement on:
+
+- Top-level types, or the type that's passed when making the first `JsonSerializer.(De)serialize` call.
+- Collection element types&mdash;the `List<string>` and `List<string?>` types are indistinguishable.
+- Any properties, fields, or constructor parameters that are generic.
+
+If you want to add nullability enforcement in these cases, either model your type to be a struct (since they don't admit null values), or author a custom converter that overrides its <xref:System.Text.Json.Serialization.JsonConverter`1.HandleNull> property to `true`.
+
+## Feature switch
+
+You can turn on the `RespectNullableAnnotations` setting globally using the `System.Text.Json.Serialization.RespectNullableAnnotationsDefault` feature switch. Add the following MSBuild item to your project file (for example, *.csproj* file):
+
+```xml
+<ItemGroup>
+  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectNullableAnnotationsDefault" Value="true" />
+</ItemGroup>
+```
+
+The `RespectNullableAnnotationsDefault` API was implemented as an opt-in flag in .NET 9 to avoid breaking existing applications. If you're writing a new application, it's highly recommended that you enable this flag in your code.
+
+## Relationship between nullable and optional parameters
+
+<xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations> doesn't extend enforcement to unspecified JSON values, because System.Text.Json treats required and non-nullable properties as orthogonal concepts. For example, the following code snippet doesn't throw an exception during deserialization:
+
+:::code language="csharp" source="snippets/nullable-annotations/Nullable.cs" id="Unspecified":::
+
+This behavior stems from the C# language itself, where you can have required properties that are nullable:
+
+```csharp
+MyPoco poco = new() { Value = null }; // No compiler warnings.
+
+class MyPoco
+{
+    public required string? Value { get; set; }
+}
+```
+
+And you can also have optional properties that are non-nullable:
+
+```csharp
+class MyPoco
+{
+    public string Value { get; set; } = "default";
+}
+```
+
+The same orthogonality applies to constructor parameters:
+
+```csharp
+record MyPoco(
+    string RequiredNonNullable,
+    string? RequiredNullable,
+    string OptionalNonNullable = "default",
+    string? OptionalNullable = "default");
+```
+
+## See also
+
+- [Non-optional constructor parameters](required-properties.md#non-optional-constructor-parameters)

docs/standard/serialization/system-text-json/required-properties.md

@@ -60,3 +60,7 @@ You can turn on the `RespectRequiredConstructorParameters` setting globally usin
 ```
 
 The `RespectRequiredConstructorParametersDefault` API was implemented as an opt-in flag in .NET 9 to avoid breaking existing applications. If you're writing a new application, it's highly recommended that you enable this flag in your code.
+
+## See also
+
+- [Respect nullable annotations](nullable-annotations.md)

docs/standard/serialization/system-text-json/snippets/nullable-annotations/Nullable.cs

@@ -0,0 +1,60 @@
+using System.Text.Json;
+
+public static class Nullable1
+{
+    // <Unspecified>
+    public static void RunIt()
+    {
+        JsonSerializerOptions options = new()
+        {
+            RespectNullableAnnotations = true
+        };
+        var result = JsonSerializer.Deserialize<MyPoco>("{}", options);
+        Console.WriteLine(result.Name is null); // True.
+    }
+
+    class MyPoco
+    {
+        public string Name { get; set; }
+    }
+    // </Unspecified>
+}
+
+public static class Nullable2
+{
+    // <Serialization>
+    public static void RunIt()
+    {
+#nullable enable
+        JsonSerializerOptions options = new()
+        {
+            RespectNullableAnnotations = true
+        };
+
+        Person invalidValue = new(Name: null!);
+        JsonSerializer.Serialize(invalidValue, options);
+    }
+
+    record Person(string Name);
+    // </Serialization>
+}
+
+public static class Nullable3
+{
+    // <Deserialization>
+    public static void RunIt()
+    {
+#nullable enable
+        JsonSerializerOptions options = new()
+        {
+            RespectNullableAnnotations = true
+        };
+
+        string json = """{"Name":null}""";
+        JsonSerializer.Deserialize<Person>(json, options);
+    }
+
+    record Person(string Name);
+    // </Deserialization>
+}
+

docs/standard/serialization/system-text-json/snippets/nullable-annotations/Program.cs

@@ -0,0 +1,3 @@
+//Nullable1.RunIt();
+//Nullable2.RunIt();
+Nullable3.RunIt();

docs/standard/serialization/system-text-json/snippets/nullable-annotations/Project.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+</Project>