Support property ordering on POCOs

[steveharter]

Background and Motivation

As part of making more extensible POCO converters and community asks, a low-risk feature for specifying ordering of properties\fields on a POCO for serialization is possible in the V6 timeframe. Other extensibility POCO features are no longer feasible for V6 since they need 1-2 preview releases to be properly vetted.

Today the serializer depends on reflection order for serializing object properties, and does base classes afterwards. Reflection is currently not deterministic and sometimes control over base class ordering is desired such as specifying base properties first.

The simplest way to implement this is through an attribute that specifies the order. However, this only works for owned POCOs. For V7+ once the JsonPropertyInfo is exposed publicly, that will allow for non-owned POCOs to also have this behavior.

Note that Newtonsoft has a similar approach with JsonPropertyAttribute.Order.

The source-generator should also leverage this attribute.

Proposed API

namespace System.Text.Json.Serialization
{
+  [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)]
+  public sealed class JsonPropertyOrderAttribute : JsonAttribute
+  {
+    public JsonPropertyNameAttribute(int order);
+    public int Order { get; }
+  }
}

Usage Examples

public class Person
{
    [JsonPropertyOrder(-1)] // Always appear first
    public int Id { get; set; }

    [JsonPropertyOrder(1)] // appear before LastName
    public string FirstName { get; set; }

    [JsonPropertyOrder(2)]
    public string LastName{ get; set; }

    public string City{ get; set; } // No order defined (has a order value of 0)
}

If there is a "tie" in the values, the reflection order is used. This is also consistent with Newtsonsoft.

Alternative Designs

It is possible to add a "strategy" pattern here, like we do for property naming. However, as mentioned in the introduction, in V7+ allowing write access to the JsonPropertyInfo.Order property will likely be the most natural mechanism once JsonPropertyInfo is exposed publicly. This would be coupled with a mechanism to retrieve all properties, allowing, for example, properties to be sorted by base class first and\or sorted alphabetically without using [JsonPropertyOrder].

Tagging subscribers to this area: @eiriktsarpalis, @layomia
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and Motivation

As part of making more extensible POCO converters and community asks, a low-risk feature for specifying ordering of properties\fields on a POCO for serialization is possible in the V6 timeframe. Other extensibility POCO features are no longer feasible for V6 since they need 1-2 preview releases to be properly vetted.

Today the serializer depends on reflection order for properties, and does base classes afterwards. Reflection is currently not deterministic and control over base class ordering is desired.

The simplest way to implement this is through an attribute that specifies the order. However, this only works for owned POCOs. For V7+ once the JsonPropertyInfo is exposed publicly, that will allow for non-owned POCOs to also have this behavior.

Note that Newtonsoft has a similar approach with JsonPropertyAttribute.Order.

The source-generator should also leverage this attribute.

Proposed API

namespace System.Text.Json.Serialization
{
+  [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)]
+  public sealed class JsonPropertyOrderAttribute : JsonAttribute
+  {
+    public JsonPropertyNameAttribute(int order);
+    public int Order { get; }
+  }
}

Usage Examples

public class Person
{
    [JsonPropertyOrder(-1)] // Always appear first
    public int Id { get; set; }

    [JsonPropertyOrder(1)] // appear before LastName
    public string FirstName { get; set; }

    [JsonPropertyOrder(2)]
    public string LastName{ get; set; }

    public string City{ get; set; } // No order defined (has a order value of 0)
}

Alternative Designs

It is possible to add a "strategy" pattern here, like we do for property naming. However, as mentioned in the introduction, in V7+ allowing write access to the JsonPropertyInfo.Order property will likely be the most natural mechanism once JsonPropertyInfo is exposed publicly. This would be coupled with a mechanism to retreive all properties, allowing, for example, properties to be sorted alphabetically automatically without using [JsonPropertyOrder].

Author:	steveharter
Assignees:	steveharter
Labels:	api-suggestion, area-System.Text.Json
Milestone:	6.0.0

[bugproof]

I think if someone wants to serialize base properties first it shouldn't be that tiresome as adding [JsonPropertyOrder] attribute to every single property. I think users should be able to implement their own sorting strategies themselves or this behaviour should be a default one. E.g. to preserve the order it's possible to order by MetadataToken. Attributes are good but aren't very flexible. JsonSerializerOptions could have some kind of sorting strategy that would be used here

runtime/src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonClassInfo.cs

Line 120 in 650f28f

foreach (PropertyInfo propertyInfo in currentType.GetProperties(bindingFlags))

[eiriktsarpalis]

[JsonPropertyOrder(-1)] // Always appear first

Trying to understand the comment: Is -1 a special value that makes the field appear first or is it using the natural ordering of integers? (i.e. a member with [JsonPropertyOrder(-2)] would always appear before the above)

[zcsizmadia]

in 728 I suggested to use a similar property ordering what Newtonsoft.Json is using, where -1 is the default value for the order if attribute is not explicitly defined. I think what @steveharter is proposing a +1 what Newtonsoft.json is doing, so 0 is the default (instead of -1), -1 is to force to be first (instead of -2).

It might make sense to define a JsonPropertyFirst() attribute , instead of using a "weird" looking negative number

[layomia]

Following offline discussion between @eiriktsarpalis and I, the proposal is to place no limitation on the integer values passed into the attribute ctor. If there are duplicates/ties, they'd be resolved by the serializer falling back to the reflection order (which would write props on derived classes first, before base). So props with order -3 would be written before -1, etc.