Property order with System.Text.Json in C#

You specify the order by assigning an integer value, with properties being serialized in ascending order.

using System.Text.Json.Serialization;

public class Employee
{    
    [JsonPropertyOrder(3)]
    public string Department { get; set; }

    [JsonPropertyOrder(1)]
    public string Name { get; set; }
    
    [JsonPropertyOrder(2)]
    public string Position { get; set; }
}

Note: Properties have a default order value of 0.

Now serialize an object to JSON:

using System.Text.Json;

var json = JsonSerializer.Serialize(new Employee()
{
    Name = "Alice Johnson",
    Position = "Software Developer",
    Department = "IT",
}, new JsonSerializerOptions() { WriteIndented = true });

Console.WriteLine(json);

This generates the following JSON:

{
  "Department": "IT",
  "Name": "Alice Johnson",
  "Position": "Software Developer"
}

Notice that the properties are serialized in ascending order based on the JsonPropertyOrder values:

• Department (3)
• Name (1)
• Position (2)

Default Property Serialization Order

When you use System.Text.Json to serialize an object, the default order of properties isn’t guaranteed. The properties are determined via reflection, and while declared properties are serialized first, there’s no guarantee about their order.

Why is There No Guaranteed Default Order?

You might assume properties would serialize in the order they’re declared in the class, but System.Text.Json uses Type.GetProperties(), and this method does not ensure an order:

The GetProperties method does not return properties in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which properties are returned, because that order varies.

This is why the JsonPropertyOrder attribute is necessary if you need to define a specific serialization order.

Declared Properties First, Then Inherited Properties

Serialization occurs in two groups:

1. Declared properties (non-inherited) are serialized first.
2. Inherited properties are serialized second.

Within these groups, no ordering is guaranteed unless you specify it.

Serialize a Base Class Property First

To ensure a property from a base class serializes first, you can apply the JsonPropertyOrder attribute to it.

using System.Text.Json.Serialization;

public abstract class Person
{
    public string Name { get; set; }
    [JsonPropertyOrder(-1000)]
    public int Id { get; set; }
}

public class Employee : Person
{
    public string Role { get; set; }
}

Now serialize an Employee object:

using System.Text.Json;

var json = JsonSerializer.Serialize(new Employee()
{
    Name = "Bruce Wayne",
    Role = "CEO",
    Id = 1
}, new JsonSerializerOptions() { WriteIndented = true });

Console.WriteLine(json);

The resulting JSON will ensure that the Id property from the Person base class appears first:

{
  "Id": 1,
  "Role": "CEO",
  "Name": "Bruce Wayne"
}

In this case, the Id property appears before the Role and Name, which are declared in the derived Employee class.

By using the JsonPropertyOrder attribute, you can control the serialization order of properties in System.Text.Json, even in scenarios involving inheritance.