[API Proposal]: Add Support for JsonAlternativePropertyNameAttribute in System.Text.Json

The issue names no repository files, tests, or entry points. Start by reviewing System.Text.Json's existing JsonPropertyNameAttribute behavior and the open questions about precedence, multiple matches, polymorphism, and converters. Done would require an agreed API and behavior specification before implementation.

Background and motivation

Could not find a similar issue - please correct me if this is a duplicate.

Summary

It would be extremely useful to have a built-in JsonAlternativePropertyNameAttribute in System.Text.Json to handle scenarios where a property might have multiple valid names in the JSON payload. This feature would simplify handling backward compatibility, versioning, and schema evolution without requiring extensive custom converters or breaking changes.

---

Problem Statement

When deserializing JSON using System.Text.Json, there is currently no straightforward way to map multiple property names in the JSON payload to a single property in a .NET class. This is particularly challenging when dealing with:

1. Typographical errors: When legacy systems or earlier versions of an API have properties with incorrect spellings (e.g., OccuredAt vs. OccurredAt).
2. Schema evolution: When properties are renamed in newer API versions, but backward compatibility must be maintained for older JSON payloads.
3. Third-party integrations: When consuming JSON from external sources where property names may vary or use different conventions.

Currently, developers must write custom JsonConverter implementations to handle such scenarios. This can be verbose, error-prone, and cumbersome, especially when working with large models or frequent schema changes.

---

Benefits

1. Simplified Code: Reduces the need for custom JsonConverter implementations to handle alternative property names.
2. Backward Compatibility: Makes it easier to maintain backward compatibility when property names evolve over time.
3. Reduced Boilerplate: Eliminates repetitive code for handling common schema evolution scenarios.
4. Improved Developer Experience: Aligns with the declarative and attribute-based design philosophy of System.Text.Json.

---

Workarounds

Currently, developers must write custom JsonConverter implementations or preprocess JSON manually to handle such cases. While this works, it introduces unnecessary complexity and duplication, especially in larger projects or libraries.

---

Considerations

1. How will multiple JsonAlternativePropertyNameAttribute values interact with each other or with JsonPropertyName?
2. Should deserialization prioritize JsonPropertyName over alternative names when multiple matches are found?
3. How will this work with existing features like polymorphic deserialization or converters?

API Proposal

Proposed Solution

Introduce a JsonAlternativePropertyNameAttribute to specify alternative names for a property during deserialization.

public class MyEvent
{
    [JsonPropertyName("OccurredAt")]
    [JsonAlternativePropertyName("OccuredAt")]
    public DateTimeOffset OccurredAt { get; set; }

    public string Name { get; set; }
}

With this attribute, the OccurredAt property would be deserialized correctly from JSON with either OccurredAt or OccuredAt as the property name.

API Usage

Expected Behavior:

Given the following JSON payloads:

{ "OccuredAt": "2025-01-01T12:00:00Z", "Name": "Event1" }
{ "OccurredAt": "2025-01-01T12:00:00Z", "Name": "Event2" }

Both should deserialize into the same object:

var myEvent = JsonSerializer.Deserialize<MyEvent>(json, options);
Console.WriteLine(myEvent.OccurredAt); // Outputs: 1/1/2025 12:00:00 PM

When serializing, the primary property name (JsonPropertyName) would be used, ensuring consistency:

var json = JsonSerializer.Serialize(myEvent);
Console.WriteLine(json); 
// Outputs: { "OccurredAt": "2025-01-01T12:00:00Z", "Name": "Event1" }

Alternative Designs

No response

Risks

No response