Breaking changes for JsonSerializer.Deserialize (#20956)

Author: gewarren

docs/core/compatibility/3.1-5.0.md

@@ -383,8 +383,13 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v
 
 ## Serialization
 
+- [JsonSerializer.Deserialize requires single-character string](#jsonserializerdeserialize-requires-single-character-string)
 - [BinaryFormatter.Deserialize rewraps some exceptions in SerializationException](#binaryformatterdeserialize-rewraps-some-exceptions-in-serializationexception)
 
+[!INCLUDE [deserializing-json-into-char-requires-single-character](../../../includes/core-changes/serialization/5.0/deserializing-json-into-char-requires-single-character.md)]
+
+***
+
 [!INCLUDE [binaryformatter-deserialize-rewraps-exceptions](../../../includes/core-changes/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md)]
 
 ***

docs/core/compatibility/serialization.md

@@ -9,9 +9,14 @@ The following breaking changes are documented on this page:
 
 | Breaking change | Introduced version |
 | - | - |
+| [JsonSerializer.Deserialize requires single-character string](#jsonserializerdeserialize-requires-single-character-string) | 5.0 |
 | [BinaryFormatter.Deserialize rewraps some exceptions in SerializationException](#binaryformatterdeserialize-rewraps-some-exceptions-in-serializationexception) | 5.0 |
 
-## .NET Core 5.0
+## .NET 5.0
+
+[!INCLUDE [deserializing-json-into-char-requires-single-character](../../../includes/core-changes/serialization/5.0/deserializing-json-into-char-requires-single-character.md)]
+
+***
 
 [!INCLUDE [binaryformatter-deserialize-rewraps-exceptions](../../../includes/core-changes/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md)]
 

includes/core-changes/serialization/5.0/deserializing-json-into-char-requires-single-character.md

@@ -0,0 +1,46 @@
+### JsonSerializer.Deserialize requires single-character string
+
+When the type parameter is <xref:System.Char>, the string argument to <xref:System.Text.Json.JsonSerializer.Deserialize%60%601(System.String,System.Text.Json.JsonSerializerOptions)?displayProperty=nameWithType> must contain a single character for deserialization to succeed.
+
+#### Change description
+
+In previous .NET versions, if you pass a multi-character string to <xref:System.Text.Json.JsonSerializer.Deserialize%60%601(System.String,System.Text.Json.JsonSerializerOptions)?displayProperty=nameWithType> and the type parameter is <xref:System.Char>, the deserialization succeeds and only the first character is deserialized.
+
+In .NET 5.0 and later, when the type parameter is <xref:System.Char>, passing anything other than a single-character string causes a <xref:System.Text.Json.JsonException> to be thrown.
+
+```csharp
+// .NET Core 3.0 and 3.1: Returns the first character 'a'.
+// .NET 5.0 and later: Throws JsonException because payload has more than one character.
+JsonSerializer.Deserialize<char>("\"abc\"");
+
+// Correct usage.
+JsonSerializer.Deserialize<char>("\"a\"");
+```
+
+#### Version introduced
+
+5.0
+
+#### Reason for change
+
+<xref:System.Text.Json.JsonSerializer.Deserialize%60%601(System.String,System.Text.Json.JsonSerializerOptions)?displayProperty=nameWithType> parses text that represents a single JSON value into an instance of the type specified by the generic type parameter. Parsing should only succeed when the provided payload is valid for the specified generic type parameter. For a <xref:System.Char> value type, a valid payload is a single character string.
+
+#### Recommended action
+
+When parsing a string into a <xref:System.Char> type using <xref:System.Text.Json.JsonSerializer.Deserialize%60%601(System.String,System.Text.Json.JsonSerializerOptions)?displayProperty=nameWithType>, make sure the string consists of a single character.
+
+#### Category
+
+Serialization
+
+#### Affected APIs
+
+- <xref:System.Text.Json.JsonSerializer.Deserialize%60%601(System.String,System.Text.Json.JsonSerializerOptions)?displayProperty=fullName>
+
+<!--
+
+#### Affected APIs
+
+- `M:System.Text.Json.JsonSerializer.Deserialize``1(System.String,System.Text.Json.JsonSerializerOptions)`
+
+-->