Customize a JSON contract

Article
06/16/2023

The System.Text.Json library constructs a JSON contract for each .NET type, which defines how the type should be serialized and deserialized. The contract is derived from the type's shape, which includes characteristics such as its properties and fields and whether it implements the IEnumerable or IDictionary interface. Types are mapped to contracts either at run time using reflection or at compile time using the source generator.

Starting in .NET 7, you can customize these JSON contracts to provide more control over how types are converted into JSON and vice versa. The following list shows just some examples of the types of customizations you can make to serialization and deserialization:

Serialize private fields and properties.
Support multiple names for a single property (for example, if a previous library version used a different name).
Ignore properties with a specific name, type, or value.
Distinguish between explicit null values and the lack of a value in the JSON payload.
Support System.Runtime.Serialization attributes, such as DataContractAttribute. For more information, see System.Runtime.Serialization attributes.
Throw an exception if the JSON includes a property that's not part of the target type. For more information, see Handle missing members.

How to opt in

There are two ways to plug into customization. Both involve obtaining a resolver, whose job is to provide a JsonTypeInfo instance for each type that needs to be serialized.

By calling the DefaultJsonTypeInfoResolver() constructor to obtain the JsonSerializerOptions.TypeInfoResolver and adding your custom actions to its Modifiers property.

For example:
```
JsonSerializerOptions options = new()
{
    TypeInfoResolver = new DefaultJsonTypeInfoResolver
    {
        Modifiers =
        {
            MyCustomModifier1,
            MyCustomModifier2
        }
    }
};
```
If you add multiple modifiers, they'll be called sequentially.
By writing a custom resolver that implements IJsonTypeInfoResolver.
- If a type isn't handled, IJsonTypeInfoResolver.GetTypeInfo should return null for that type.
- You can also combine your custom resolver with others, for example, the default resolver. The resolvers will be queried in order until a non-null JsonTypeInfo value is returned for the type.

Configurable aspects

The JsonTypeInfo.Kind property indicates how the converter serializes a given type—for example, as an object or as an array, and whether its properties are serialized. You can query this property to determine which aspects of a type's JSON contract you can configure. There are four different kinds:

`JsonTypeInfo.Kind`	Description
JsonTypeInfoKind.Object	The converter will serialize the type into a JSON object and uses its properties. This kind is used for most class and struct types and allows for the most flexibility.
JsonTypeInfoKind.Enumerable	The converter will serialize the type into a JSON array. This kind is used for types like `List<T>` and array.
JsonTypeInfoKind.Dictionary	The converter will serialize the type into a JSON object. This kind is used for types like `Dictionary<K, V>`.
JsonTypeInfoKind.None	The converter doesn't specify how it will serialize the type or what `JsonTypeInfo` properties it will use. This kind is used for types like System.Object, `int`, and `string`, and for all types that use a custom converter.

Modifiers

A modifier is an Action<JsonTypeInfo> or a method with a JsonTypeInfo parameter that gets the current state of the contract as an argument and makes modifications to the contract. For example, you could iterate through the prepopulated properties on the specified JsonTypeInfo to find the one you're interested in and then modify its JsonPropertyInfo.Get property (for serialization) or JsonPropertyInfo.Set property (for deserialization). Or, you can construct a new property using JsonTypeInfo.CreateJsonPropertyInfo(Type, String) and add it to the JsonTypeInfo.Properties collection.

The following table shows the modifications you can make and how to achieve them.

Modification	Applicable `JsonTypeInfo.Kind`	How to achieve it	Example
Customize a property's value	`JsonTypeInfoKind.Object`	Modify the JsonPropertyInfo.Get delegate (for serialization) or JsonPropertyInfo.Set delegate (for deserialization) for the property.	Increment a property's value
Add or remove properties	`JsonTypeInfoKind.Object`	Add or remove items from the JsonTypeInfo.Properties list.	Serialize private fields
Conditionally serialize a property	`JsonTypeInfoKind.Object`	Modify the JsonPropertyInfo.ShouldSerialize predicate for the property.	Ignore properties with a specific type
Customize number handling for a specific type	`JsonTypeInfoKind.None`	Modify the JsonTypeInfo.NumberHandling value for the type.	Allow int values to be strings

Example: Increment a property's value

Consider the following example where the modifier increments the value of a certain property on deserialization by modifying its JsonPropertyInfo.Set delegate. Besides defining the modifier, the example also introduces a new attribute that it uses to locate the property whose value should be incremented. This is an example of customizing a property.

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

namespace Serialization
{
    // Custom attribute to annotate the property
    // we want to be incremented.
    [AttributeUsage(AttributeTargets.Property)]
    class SerializationCountAttribute : Attribute
    {
    }

    // Example type to serialize and deserialize.
    class Product
    {
        public string Name { get; set; } = "";
        [SerializationCount]
        public int RoundTrips { get; set; }
    }

    public class SerializationCountExample
    {
        // Custom modifier that increments the value
        // of a specific property on deserialization.
        static void IncrementCounterModifier(JsonTypeInfo typeInfo)
        {
            foreach (JsonPropertyInfo propertyInfo in typeInfo.Properties)
            {
                if (propertyInfo.PropertyType != typeof(int))
                    continue;

                object[] serializationCountAttributes = propertyInfo.AttributeProvider?.GetCustomAttributes(typeof(SerializationCountAttribute), true) ?? Array.Empty<object>();
                SerializationCountAttribute? attribute = serializationCountAttributes.Length == 1 ? (SerializationCountAttribute)serializationCountAttributes[0] : null;

                if (attribute != null)
                {
                    Action<object, object?>? setProperty = propertyInfo.Set;
                    if (setProperty is not null)
                    {
                        propertyInfo.Set = (obj, value) =>
                        {
                            if (value != null)
                            {
                                // Increment the value by 1.
                                value = (int)value + 1;
                            }

                            setProperty (obj, value);
                        };
                    }
                }
            }
        }

        public static void RunIt()
        {
            var product = new Product
            {
                Name = "Aquafresh"
            };

            JsonSerializerOptions options = new()
            {
                TypeInfoResolver = new DefaultJsonTypeInfoResolver
                {
                    Modifiers = { IncrementCounterModifier }
                }
            };

            // First serialization and deserialization.
            string serialized = JsonSerializer.Serialize(product, options);
            Console.WriteLine(serialized);
            // {"Name":"Aquafresh","RoundTrips":0}

            Product deserialized = JsonSerializer.Deserialize<Product>(serialized, options)!;
            Console.WriteLine($"{deserialized.RoundTrips}");
            // 1

            // Second serialization and deserialization.
            serialized = JsonSerializer.Serialize(deserialized, options);
            Console.WriteLine(serialized);
            // { "Name":"Aquafresh","RoundTrips":1}

            deserialized = JsonSerializer.Deserialize<Product>(serialized, options)!;
            Console.WriteLine($"{deserialized.RoundTrips}");
            // 2
        }
    }
}

Notice in the output that the value of RoundTrips is incremented each time the Product instance is deserialized.

Example: Serialize private fields

By default, System.Text.Json ignores private fields and properties. This example adds a new class-wide attribute, JsonIncludePrivateFieldsAttribute, to change that default. If the modifier finds the attribute on a type, it adds all the private fields on the type as new properties to JsonTypeInfo.

using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Text.Json.Serialization.Metadata;

namespace Serialization
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
    public class JsonIncludePrivateFieldsAttribute : Attribute { }

    [JsonIncludePrivateFields]
    public class Human
    {
        private string _name;
        private int _age;

        public Human()
        {
            // This constructor should be used only by deserializers.
            _name = null!;
            _age = 0;
        }

        public static Human Create(string name, int age)
        {
            Human h = new()
            {
                _name = name,
                _age = age
            };

            return h;
        }

        [JsonIgnore]
        public string Name
        {
            get => _name;
            set => throw new NotSupportedException();
        }

        [JsonIgnore]
        public int Age
        {
            get => _age;
            set => throw new NotSupportedException();
        }
    }

    public class PrivateFieldsExample
    {
        static void AddPrivateFieldsModifier(JsonTypeInfo jsonTypeInfo)
        {
            if (jsonTypeInfo.Kind != JsonTypeInfoKind.Object)
                return;

            if (!jsonTypeInfo.Type.IsDefined(typeof(JsonIncludePrivateFieldsAttribute), inherit: false))
                return;

            foreach (FieldInfo field in jsonTypeInfo.Type.GetFields(BindingFlags.Instance | BindingFlags.NonPublic))
            {
                JsonPropertyInfo jsonPropertyInfo = jsonTypeInfo.CreateJsonPropertyInfo(field.FieldType, field.Name);
                jsonPropertyInfo.Get = field.GetValue;
                jsonPropertyInfo.Set = field.SetValue;

                jsonTypeInfo.Properties.Add(jsonPropertyInfo);
            }
        }

        public static void RunIt()
        {
            var options = new JsonSerializerOptions
            {
                TypeInfoResolver = new DefaultJsonTypeInfoResolver
                {
                    Modifiers = { AddPrivateFieldsModifier }
                }
            };

            var human = Human.Create("Julius", 37);
            string json = JsonSerializer.Serialize(human, options);
            Console.WriteLine(json);
            // {"_name":"Julius","_age":37}

            Human deserializedHuman = JsonSerializer.Deserialize<Human>(json, options)!;
            Console.WriteLine($"[Name={deserializedHuman.Name}; Age={deserializedHuman.Age}]");
            // [Name=Julius; Age=37]
        }
    }
}

Tip

If your private field names start with underscores, consider removing the underscores from the names when you add the fields as new JSON properties.

Example: Ignore properties with a specific type

Perhaps your model has properties with specific names or types that you don't want to expose to users. For example, you might have a property that stores credentials or some information that's useless to have in the payload.

The following example shows how to filter out properties with a specific type, SecretHolder. It does this by using an IList<T> extension method to remove any properties that have the specified type from the JsonTypeInfo.Properties list. The filtered properties completely disappear from the contract, which means System.Text.Json doesn't look at them either during serialization or deserialization.

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

namespace Serialization
{
    class ExampleClass
    {
        public string Name { get; set; } = "";
        public SecretHolder? Secret { get; set; }
    }

    class SecretHolder
    {
        public string Value { get; set; } = "";
    }

    class IgnorePropertiesWithType
    {
        private readonly Type[] _ignoredTypes;

        public IgnorePropertiesWithType(params Type[] ignoredTypes)
            => _ignoredTypes = ignoredTypes;

        public void ModifyTypeInfo(JsonTypeInfo ti)
        {
            if (ti.Kind != JsonTypeInfoKind.Object)
                return;

            ti.Properties.RemoveAll(prop => _ignoredTypes.Contains(prop.PropertyType));
        }
    }

    public class IgnoreTypeExample
    {
        public static void RunIt()
        {
            var modifier = new IgnorePropertiesWithType(typeof(SecretHolder));

            JsonSerializerOptions options = new()
            {
                TypeInfoResolver = new DefaultJsonTypeInfoResolver
                {
                    Modifiers = { modifier.ModifyTypeInfo }
                }
            };

            ExampleClass obj = new()
            {
                Name = "Password",
                Secret = new SecretHolder { Value = "MySecret" }
            };

            string output = JsonSerializer.Serialize(obj, options);
            Console.WriteLine(output);
            // {"Name":"Password"}
        }
    }

    public static class ListHelpers
    {
        // IList<T> implementation of List<T>.RemoveAll method.
        public static void RemoveAll<T>(this IList<T> list, Predicate<T> predicate)
        {
            for (int i = 0; i < list.Count; i++)
            {
                if (predicate(list[i]))
                {
                    list.RemoveAt(i--);
                }
            }
        }
    }
}

Example: Allow int values to be strings

Perhaps your input JSON can contain quotes around one of the numeric types but not on others. If you had control over the class, you could place JsonNumberHandlingAttribute on the type to fix this, but you don't. Before .NET 7, you'd need to write a custom converter to fix this behavior, which requires writing a fair bit of code. Using contract customization, you can customize the number handling behavior for any type.

The following example changes the behavior for all int values. The example can be easily adjusted to apply to any type or for a specific property of any type.

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

namespace Serialization
{
    public class Point
    {
        public int X { get; set; }
        public int Y { get; set; }
    }

    public class AllowIntsAsStringsExample
    {
        static void SetNumberHandlingModifier(JsonTypeInfo jsonTypeInfo)
        {
            if (jsonTypeInfo.Type == typeof(int))
            {
                jsonTypeInfo.NumberHandling = JsonNumberHandling.AllowReadingFromString;
            }
        }

        public static void RunIt()
        {
            JsonSerializerOptions options = new()
            {
                TypeInfoResolver = new DefaultJsonTypeInfoResolver
                {
                    Modifiers = { SetNumberHandlingModifier }
                }
            };

            // Triple-quote syntax is a C# 11 feature.
            Point point = JsonSerializer.Deserialize<Point>("""{"X":"12","Y":"3"}""", options)!;
            Console.WriteLine($"({point.X},{point.Y})");
            // (12,3)
        }
    }
}

Without the modifier to allow reading int values from a string, the program would have ended with an exception:

Unhandled exception. System.Text.Json.JsonException: The JSON value could not be converted to System.Int32. Path: $.X | LineNumber: 0 | BytePositionInLine: 9.

Other ways to customize serialization

Besides customizing a contract, there are other ways to influence serialization and deserialization behavior, including the following:

By using attributes derived from JsonAttribute, for example, JsonIgnoreAttribute and JsonPropertyOrderAttribute.
By modifying JsonSerializerOptions, for example, to set a naming policy or serialize enumeration values as strings instead of numbers.
By writing a custom converter that does the actual work of writing the JSON and, during deserialization, constructing an object.

Contract customization is an improvement over these pre-existing customizations because you might not have access to the type to add attributes, and writing a custom converter is complex and hurts performance.