Round-trip default(struct union) ↔ JSON null

A `default(struct union)` has no selected case and its `Value` returns null.
Previously the deconstructor threw `UnionDoesNotAcceptNull` in that state, so
`JsonSerializer.Serialize(new Container())` crashed at the union property even
when the container was newly constructed and the union was untouched. The C#
compiler's CS8655 already treats this null state as part of every union's
domain — a `value switch` on any union requires a `null` arm.

Align serialization with that contract:

* The reflection deconstructor returns `(null, null)` when `Value` is null
  and no nullable case exists (and dispatches through the nullable case when
  one is present).
* The source-generated emitter always emits a `null =>` switch arm: a typed
  arm when a nullable case exists, or
  `null => ((global::System.Type?)null, (object?)null)` otherwise.
* `JsonUnionConverter` already writes JSON null when the deconstructor reports
  `(null, null)`.

For symmetry on the read side, `JsonUnionConverter.OnTryRead` now produces
`default(TUnion)` instead of throwing when JSON null arrives for a union with
no nullable case. This makes `default(union) → "null" → default(union)` a
full round-trip. The constructor-delegate contract is unchanged — callers that
invoke the delegate directly with `null` on a non-nullable union still see
`UnionDoesNotAcceptNull`.

Add round-trip tests for `NoNullableCaseUnion`, its container, and a new
`IntOrBool` (`union IntOrBool(int, bool);`) that mirrors the exact repro
shape from the issue.

Fixes #128834

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: eiriktsarpalis

src/libraries/System.Text.Json/gen/JsonSourceGenerator.Emitter.cs

@@ -731,6 +731,14 @@ private static SourceText GenerateForUnion(ContextGenerationSpec contextSpec, Ty
                     {
                         writer.WriteLine($"null => (typeof({nullCase.CaseType.FullyQualifiedName}), (object?)null),");
                     }
+                    else
+                    {
+                        // Always emit a null arm. C# pattern matching treats default(union)
+                        // as the null state (CS8655) and the union's Value property returns
+                        // null in that state. Routing to (null, null) signals
+                        // JsonUnionConverter to write JSON null instead of throwing.
+                        writer.WriteLine("null => ((global::System.Type?)null, (object?)null),");
+                    }
 
                     // unionCases is in topological most-derived-first order, so the first
                     // matching arm always corresponds to the nearest declared case for any

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Union/JsonUnionConverter.cs

@@ -43,7 +43,13 @@ internal override bool OnTryRead(ref Utf8JsonReader reader, Type typeToConvert,
                 Type? nullableCaseType = typeInfo.UnionNullableCaseType;
                 if (nullableCaseType is null)
                 {
-                    ThrowHelper.ThrowJsonException_UnionDoesNotAcceptNull(typeToConvert);
+                    // Round-trip symmetry with the serializer: default(union) writes
+                    // JSON null (deconstructor returns (null, null)), so JSON null must
+                    // read back as default(union). For value-type unions this is the
+                    // zero-init struct; for reference-type unions this is null.
+                    // See https://github.com/dotnet/runtime/issues/128834.
+                    value = default;
+                    return true;
                 }
 
                 value = constructor(nullableCaseType, null);

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Metadata/DefaultJsonTypeInfoResolver.Union.cs

@@ -234,12 +234,15 @@ private static void PopulateUnionDeconstructor(
                     object? value = valueAccessor(union);
                     if (value is null)
                     {
-                        if (nullableCase is null)
-                        {
-                            ThrowHelper.ThrowJsonException_UnionDoesNotAcceptNull(typeof(TUnion));
-                        }
-
-                        return (nullableCase.CaseType, null);
+                        // Always succeed on null. Two scenarios converge here:
+                        //   (1) default(struct union) has no case set and Value returns null.
+                        //   (2) A nullable case was constructed with null (Foo((string?)null)).
+                        // When a nullable case exists, dispatch through it so the converter
+                        // calls the case's own converter for null. Otherwise return
+                        // (null, null) — JsonUnionConverter writes JSON null in that case.
+                        return nullableCase is not null
+                            ? (nullableCase.CaseType, null)
+                            : (null, null);
                     }
 
                     Type runtimeType = value.GetType();

src/libraries/System.Text.Json/tests/Common/UnionTests.cs

@@ -465,11 +465,19 @@ public void Deconstructor_NullUnionInstance_ReturnsNullCaseTypeAndValue()
         }
 
         [Fact]
-        public void Deconstructor_UnionWithNullValue_NoNullableCase_Throws()
+        public void Deconstructor_UnionWithNullValue_NoNullableCase_ReturnsNullPair()
         {
+            // The deconstructor must succeed when a case payload is null even on a union
+            // with no nullable case (e.g. HierarchyUnion(Animal) where Animal is declared
+            // non-nullable but the user passed null!). Returning (null, null) signals
+            // JsonUnionConverter to write JSON null — matching the class-record behavior
+            // described in https://github.com/dotnet/runtime/issues/128834.
             JsonTypeInfo<HierarchyUnion> typeInfo = Serializer.GetTypeInfo<HierarchyUnion>();
 
-            Assert.ThrowsAny<Exception>(() => typeInfo.UnionDeconstructor!(new HierarchyUnion((Animal)null!)));
+            (Type? caseType, object? caseValue) = typeInfo.UnionDeconstructor!(new HierarchyUnion((Animal)null!));
+
+            Assert.Null(caseType);
+            Assert.Null(caseValue);
         }
 
         [Fact]
@@ -536,6 +544,19 @@ public void Constructor_NullValue_NullableCaseExists_BuildsViaNullableCtor()
 
         public union NoNullableCaseUnion(int);
 
+        public class NoNullableCaseUnionContainer
+        {
+            public NoNullableCaseUnion Union { get; set; }
+            public int After { get; set; }
+        }
+
+        public union IntOrBool(int, bool);
+
+        public class IntOrBoolContainer
+        {
+            public IntOrBool Value { get; set; }
+        }
+
         [Fact]
         public void Constructor_NullValue_NoNullableCase_Throws()
         {
@@ -546,6 +567,129 @@ public void Constructor_NullValue_NoNullableCase_Throws()
             Assert.ThrowsAny<Exception>(() => typeInfo.UnionConstructor!(typeof(int), null));
         }
 
+        [Fact]
+        public void Deconstructor_DefaultValueOfStructUnion_NoNullableCase_ReturnsNullPair()
+        {
+            JsonTypeInfo<NoNullableCaseUnion> typeInfo = Serializer.GetTypeInfo<NoNullableCaseUnion>();
+            Assert.NotNull(typeInfo.UnionDeconstructor);
+
+            (Type? caseType, object? caseValue) = typeInfo.UnionDeconstructor!(default);
+
+            Assert.Null(caseType);
+            Assert.Null(caseValue);
+        }
+
+        [Fact]
+        public async Task RoundTrip_DefaultValueOfStructUnion_NoNullableCase()
+        {
+            string json = await Serializer.SerializeWrapper(default(NoNullableCaseUnion));
+            Assert.Equal("null", json);
+
+            // Symmetry: JSON null must deserialize back to default(NoNullableCaseUnion),
+            // which deconstructs to (null, null) — the same shape that produced the JSON.
+            NoNullableCaseUnion roundtripped = await Serializer.DeserializeWrapper<NoNullableCaseUnion>(json);
+            JsonTypeInfo<NoNullableCaseUnion> typeInfo = Serializer.GetTypeInfo<NoNullableCaseUnion>();
+            (Type? caseType, object? caseValue) = typeInfo.UnionDeconstructor!(roundtripped);
+            Assert.Null(caseType);
+            Assert.Null(caseValue);
+        }
+
+        [Fact]
+        public async Task RoundTrip_ContainerWithDefaultStructUnionProperty()
+        {
+            string json = await Serializer.SerializeWrapper(new NoNullableCaseUnionContainer { After = 7 });
+            JsonTestHelper.AssertJsonEqual("""{"Union":null,"After":7}""", json);
+
+            NoNullableCaseUnionContainer? roundtripped =
+                await Serializer.DeserializeWrapper<NoNullableCaseUnionContainer>(json);
+            Assert.NotNull(roundtripped);
+            Assert.Equal(7, roundtripped.After);
+
+            JsonTypeInfo<NoNullableCaseUnion> typeInfo = Serializer.GetTypeInfo<NoNullableCaseUnion>();
+            (Type? caseType, object? caseValue) = typeInfo.UnionDeconstructor!(roundtripped.Union);
+            Assert.Null(caseType);
+            Assert.Null(caseValue);
+        }
+
+        [Fact]
+        public async Task RoundTrip_ContainerWithMissingUnionProperty_DoesNotThrowOnReserialize()
+        {
+            NoNullableCaseUnionContainer? container =
+                await Serializer.DeserializeWrapper<NoNullableCaseUnionContainer>("""{"After":7}""");
+            Assert.NotNull(container);
+            Assert.Equal(7, container.After);
+
+            // Step 2: serialize the same instance back. The union property must come
+            // back as JSON null — the round-trip must not throw.
+            string json = await Serializer.SerializeWrapper(container);
+            JsonTestHelper.AssertJsonEqual("""{"Union":null,"After":7}""", json);
+        }
+
+        [Fact]
+        public void Deconstructor_DefaultValueOfIntOrBool_ReturnsNullPair()
+        {
+            JsonTypeInfo<IntOrBool> typeInfo = Serializer.GetTypeInfo<IntOrBool>();
+            Assert.NotNull(typeInfo.UnionDeconstructor);
+
+            (Type? caseType, object? caseValue) = typeInfo.UnionDeconstructor!(default);
+
+            Assert.Null(caseType);
+            Assert.Null(caseValue);
+        }
+
+        [Fact]
+        public async Task RoundTrip_DefaultValueOfIntOrBool()
+        {
+            string json = await Serializer.SerializeWrapper(default(IntOrBool));
+            Assert.Equal("null", json);
+
+            // Symmetry: JSON null must deserialize back to default(IntOrBool).
+            IntOrBool roundtripped = await Serializer.DeserializeWrapper<IntOrBool>(json);
+            JsonTypeInfo<IntOrBool> typeInfo = Serializer.GetTypeInfo<IntOrBool>();
+            (Type? caseType, object? caseValue) = typeInfo.UnionDeconstructor!(roundtripped);
+            Assert.Null(caseType);
+            Assert.Null(caseValue);
+        }
+
+        [Fact]
+        public async Task RoundTrip_NewContainerOfIntOrBool()
+        {
+            // Exact translation of `JsonSerializer.Serialize(new Container())` from the
+            // issue comment: the container holds a non-nullable IntOrBool whose default
+            // value has no case selected. Before the fix this threw
+            // UnionDoesNotAcceptNull at $.Value. Now it must succeed and emit
+            // {"Value":null} — and the resulting JSON must round-trip back to a
+            // semantically identical container.
+            string json = await Serializer.SerializeWrapper(new IntOrBoolContainer());
+            JsonTestHelper.AssertJsonEqual("""{"Value":null}""", json);
+
+            IntOrBoolContainer? roundtripped =
+                await Serializer.DeserializeWrapper<IntOrBoolContainer>(json);
+            Assert.NotNull(roundtripped);
+
+            JsonTypeInfo<IntOrBool> typeInfo = Serializer.GetTypeInfo<IntOrBool>();
+            (Type? caseType, object? caseValue) = typeInfo.UnionDeconstructor!(roundtripped.Value);
+            Assert.Null(caseType);
+            Assert.Null(caseValue);
+        }
+
+        [Fact]
+        public void Deconstructor_DefaultValueOfIntOrBool_NonDefaultPayload_DispatchesNormally()
+        {
+            // Regression guard: the always-null arm must not shadow the per-case arms.
+            // Construct IntOrBool with a non-null value and verify the deconstructor
+            // still reports the right case type.
+            JsonTypeInfo<IntOrBool> typeInfo = Serializer.GetTypeInfo<IntOrBool>();
+
+            (Type? intCaseType, object? intCaseValue) = typeInfo.UnionDeconstructor!(new IntOrBool(42));
+            Assert.Equal(typeof(int), intCaseType);
+            Assert.Equal(42, intCaseValue);
+
+            (Type? boolCaseType, object? boolCaseValue) = typeInfo.UnionDeconstructor!(new IntOrBool(true));
+            Assert.Equal(typeof(bool), boolCaseType);
+            Assert.Equal(true, boolCaseValue);
+        }
+
         [Fact]
         public void Constructor_NullValueAndNullCaseType_RoutesToNullableCase()
         {

src/libraries/System.Text.Json/tests/System.Text.Json.SourceGeneration.Tests/Serialization/UnionTests.cs

@@ -21,6 +21,9 @@ public UnionTests_Metadata()
         [JsonSerializable(typeof(HierarchyUnion))]
         [JsonSerializable(typeof(NullableCaseUnion))]
         [JsonSerializable(typeof(NoNullableCaseUnion))]
+        [JsonSerializable(typeof(NoNullableCaseUnionContainer))]
+        [JsonSerializable(typeof(IntOrBool))]
+        [JsonSerializable(typeof(IntOrBoolContainer))]
         [JsonSerializable(typeof(ValueTypeNullablePairUnion))]
         [JsonSerializable(typeof(SingleNullableValueTypeUnion))]
         [JsonSerializable(typeof(SingleObjectUnion))]
@@ -78,6 +81,9 @@ public UnionTests_Default()
         [JsonSerializable(typeof(HierarchyUnion))]
         [JsonSerializable(typeof(NullableCaseUnion))]
         [JsonSerializable(typeof(NoNullableCaseUnion))]
+        [JsonSerializable(typeof(NoNullableCaseUnionContainer))]
+        [JsonSerializable(typeof(IntOrBool))]
+        [JsonSerializable(typeof(IntOrBoolContainer))]
         [JsonSerializable(typeof(ValueTypeNullablePairUnion))]
         [JsonSerializable(typeof(SingleNullableValueTypeUnion))]
         [JsonSerializable(typeof(SingleObjectUnion))]