Edit

Share via

Nullable JsonDocument properties deserialize to JsonValueKind.Null

  • Article

Starting with .NET 9, deserializing null JSON values into JsonDocument results in non-null documents of type JsonValueKind.Null.

using System.Text.Json;

var doc = JsonSerializer.Deserialize<JsonDocument>("null");

// Returns true in .NET 8 and false in .NET 9.
Console.WriteLine(doc is null);

// Returns false in .NET 8 and true in .NET 9.
Console.WriteLine(doc is { RootElement.ValueKind: JsonValueKind.Null });

Version introduced

.NET 9

Previous behavior

In .NET 8 and earlier versions, deserializing null JSON values into JsonDocument gives back null results.

var doc = JsonSerializer.Deserialize<JsonDocument>("null");
Console.WriteLine(doc is null); // True.

New behavior

Starting in .NET 9, deserializing null JSON values into JsonDocument gives back non-null instances of JsonValueKind.Null.

var doc = JsonSerializer.Deserialize<JsonDocument>("null");
Console.WriteLine(doc is null); // False.
Console.WriteLine(doc is { RootElement.ValueKind: JsonValueKind.Null }); // True.

Type of breaking change

This change is a behavioral change.

Reason for change

This change addresses an inconsistency between root-level JSON nulls and nested nulls in a document. It also makes it consistent with the behavior of the JsonDocument.Parse methods. The behavior of returning null was considered a bug and updated for alignment with the expected result.

Update code that consumes deserialized objects containing JsonDocument types to expect JsonValueKind.Null instead of null.

Affected APIs