Document breaking change: System.Text.Json validates metadata property conflicts

[Copilot]

Summary

Documents the .NET 10 breaking change where System.Text.Json now validates that user-defined property names don't conflict with reserved metadata properties ($type, $id, $ref), preventing ambiguous JSON output and deserialization failures.

Previously, conflicting property names would produce duplicate properties in JSON and fail silently during deserialization:

[JsonPolymorphic(TypeDiscriminatorPropertyName = "Type")]
[JsonDerivedType(typeof(Dog), "dog")]
public abstract class Animal
{
    public abstract string Type { get; }  // Conflicts with metadata property
}

// Before .NET 10: Serializes to {"Type":"dog","Type":"Dog"} - invalid JSON
// .NET 10: Throws InvalidOperationException during serialization

Changes:

• Created breaking change article at serialization/10/json-validates-metadata-property-names.md
• Updated TOC and 10.0.md index under Serialization section
• Included remediation guidance: use JsonIgnoreAttribute or rename conflicting properties
• Added references to the original runtime issue (dotnet/runtime#106390) and PR (dotnet/runtime#106460)

Fixes #49879

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: System.Text.Json now validates property names conflicting with metadata properties</issue_title>
<issue_description>### Description

Under certain contexts (polymorphism, reference preservation) System.Text.Json reserves specific property names that it uses to emit metadata over the wire: $type, $id, $ref, etc. It does so however without performing any validation on whether these property names conflict with user-defined contracts. In such situations, STJ would emit duplicate properties and produce JSON that is ambiguous or fails to roundtrip. Starting with .NET 10, STJ enables validation preventing such configurations, giving early warning to users.

Version

.NET 10

Previous behavior

The following code:

using System.Text.Json;
using System.Text.Json.Serialization;

string json = JsonSerializer.Serialize<Animal>(new Dog());
Console.WriteLine(json); // {"Type":"dog","Type":"Dog"}
JsonSerializer.Deserialize<Animal>(json); // JsonException: Deserialized object contains a duplicate 'Type' metadata property. 

[JsonPolymorphic(TypeDiscriminatorPropertyName = "Type")]
[JsonDerivedType(typeof(Dog), "dog")]
public abstract class Animal
{
    public abstract string Type { get; }
}

public class Dog : Animal
{
    public override string Type => "Dog";
}

Will produce an invalid JSON object and fail to deserialize with a deserialization exception

New behavior

Starting with .NET 10 any attempt to serialize that same type will result in an early validation error:

InvalidOperationException: The type 'Dog' contains property 'Type' that conflicts with an existing metadata property name. Consider either renaming it or ignoring it with JsonIgnoreAttribute

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

Provides early prevention of invalid serialization contracts.

Recommended action

Users should avoid using property names that conflict with STJ specific metadata. If absolutely necessary to keep such a property around, a JsonIgnore annotation should be applied on the conflicting property.

Feature area

Serialization

Affected APIs

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

Custom agent used: breakingchange-creator
Agent that specializes in creating breaking change articles

• Fixes [Breaking change]: System.Text.Json now validates property names conflicting with metadata properties #49879

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/10.0.md	Breaking changes in .NET 10
docs/core/compatibility/serialization/10/property-name-validation.md	System.Text.Json checks for property name conflicts
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[jeffhandley]

@copilot Please mention the original issue and pull request related to this change:

• [STJ] Disallow property names that conflict with metadata property names (dotnet/runtime#106390)
• Disallow types with property names conflicting with metadata. (dotnet/runtime#106460)

[Copilot]

@copilot Please mention the original issue and pull request related to this change:

• [[STJ] Disallow property names that conflict with metadata property names ([STJ] Disallow property names that conflict with metadata property names runtime#106390)](https://github....

Added references to the original runtime issue and PR in the "Reason for change" section (commit a54af5d).

[Copilot]

Pull Request Overview

This PR documents a .NET 10 breaking change where System.Text.Json now validates that user-defined property names don't conflict with reserved metadata properties ($type, $id, $ref), preventing ambiguous JSON output and deserialization failures.

Key changes:

• Created a new breaking change article documenting the validation behavior
• Updated the TOC and version index to include the new article

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/core/compatibility/serialization/10/property-name-validation.md	New breaking change article documenting the property name conflict validation
docs/core/compatibility/toc.yml	Added TOC entry for the new breaking change article
docs/core/compatibility/10.0.md	Added index entry for the new breaking change in the Serialization section