Sysem.Text.Json: Working with Polymorphic types

Introduction

Dealing with hierarchical data structures is commonplace. Often, a base class might have several derived classes, each with its own specific properties and behaviors. When it comes to serializing and deserializing such polymorphic types using System.Text.Json in .NET, special considerations are needed to ensure data integrity and accurate representation. This article dives deep into how System.Text.Json handles polymorphic types, providing you with the knowledge and code examples to effectively work with them.

We check the flow of blew image:

Understanding Polymorphism in Serialization

Polymorphism, in the context of serialization, refers to the ability to handle objects of different derived types through a common base type. When serializing a collection of base type objects, some might actually be instances of derived types. The key challenge is to preserve the specific type information during serialization so that it can be accurately reconstructed (deserialized) later.

Enabling Polymorphic Serialization with Attributes (for .NET 7 and later)

Starting with .NET 7, System.Text.Json introduced built-in support for polymorphic type hierarchy serialization and deserialization through the use of attributes. This provides a declarative way to specify how polymorphism should be handled for your types.

The primary attributes you'll work with are:

• JsonDerivedTypeAttribute: Placed on a base type declaration, this attribute indicates that a specific subtype should be included in polymorphic serialization. It also allows you to specify a type discriminator, a value that identifies the derived type in the serialized JSON.

• JsonPolymorphicAttribute: Placed on a base type declaration, this attribute signifies that the type should be serialized polymorphically. It offers various options to configure the process, including the type discriminator property name and how to handle unknown derived types.

Let's consider a scenario with a base class WeatherForecastBase and a derived class WeatherForecastWithCity:

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

[JsonDerivedType(typeof(WeatherForecastWithCity))]
public class WeatherForecastBase
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
}

public class WeatherForecastWithCity : WeatherForecastBase
{
    public string? City { get; set; }
}

public class Program
{
    public static void Main(string[] args)
    {
        var weatherForecastBase = new WeatherForecastWithCity
        {
            Date = DateTime.Parse("2024-01-01"),
            TemperatureCelsius = 10,
            Summary = "Cloudy",
            City = "London"
        };

        var options = new JsonSerializerOptions { WriteIndented = true };
        string jsonString = JsonSerializer.Serialize<WeatherForecastBase>(weatherForecastBase, options);
        Console.WriteLine(jsonString);
    }
}

In this initial setup, even though we are serializing a WeatherForecastWithCity object as its base type WeatherForecastBase, the City property will be included in the JSON output:

{
  "City": "London",
  "Date": "2024-01-01T00:00:00+00:00",
  "TemperatureCelsius": 10,
  "Summary": "Cloudy"
}

However, during deserialization back to WeatherForecastBase, the runtime type will be WeatherForecastBase, and the City information will be lost.

Introducing Type Discriminators for Round-Tripping

To enable proper polymorphic deserialization, we need to introduce a type discriminator. This metadata helps System.Text.Json identify the actual derived type during deserialization. We achieve this using the typeDiscriminator parameter in the JsonDerivedTypeAttribute:

[JsonDerivedType(typeof(WeatherForecastBase), typeDiscriminator: "base")]
[JsonDerivedType(typeof(WeatherForecastWithCity), typeDiscriminator: "withCity")]
public class WeatherForecastBase
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
}

public class WeatherForecastWithCity : WeatherForecastBase
{
    public string? City { get; set; }
}

public class Program
{
    public static void Main(string[] args)
    {
        var weather = new WeatherForecastWithCity
        {
            City = "Milwaukee",
            Date = new DateTimeOffset(2022, 9, 26, 0, 0, 0, TimeSpan.FromHours(-5)),
            TemperatureCelsius = 15,
            Summary = "Cool"
        };
        var options = new JsonSerializerOptions { WriteIndented = true };
        var json = JsonSerializer.Serialize<WeatherForecastBase>(weather, options);
        Console.WriteLine(json);

        WeatherForecastBase? value = JsonSerializer.Deserialize<WeatherForecastBase>(json);
        Console.WriteLine(value is WeatherForecastWithCity);
    }
}

Now, the serialized JSON will include a default $type property with the specified discriminator:

{
  "$type": "withCity",
  "City": "Milwaukee",
  "Date": "2022-09-26T00:00:00-05:00",
  "TemperatureCelsius": 15,
  "Summary": "Cool"
}

And during deserialization, System.Text.Json can correctly identify and instantiate a WeatherForecastWithCity object, making value is WeatherForecastWithCity evaluate to true.

Customizing the Type Discriminator Name

The default type discriminator property name is $type. You can customize this using the TypeDiscriminatorPropertyName property of the JsonPolymorphicAttribute:

[JsonPolymorphic(TypeDiscriminatorPropertyName = "$point-type")]
[JsonDerivedType(typeof(ThreeDimensionalPoint), typeDiscriminator: "3d")]
public class BasePoint
{
    public int X { get; set; }
    public int Y { get; set; }
}

public sealed class ThreeDimensionalPoint : BasePoint
{
    public int Z { get; set; }
}

public class Program
{
    public static void Main(string[] args)
    {
        BasePoint point = new ThreeDimensionalPoint { X = 1, Y = 2, Z = 3 };
        var json = JsonSerializer.Serialize<BasePoint>(point);
        Console.WriteLine(json);
    }
}

The output will now use the custom discriminator name:

{
  "$point-type": "3d",
  "X": 1,
  "Y": 2,
  "Z": 3
}

Handling Unknown Derived Types

By default, if System.Text.Json encounters a type discriminator in the JSON that doesn't correspond to any JsonDerivedTypeAttribute on the base type, it will throw a NotSupportedException during deserialization. You can customize this behavior using the UnknownDerivedTypeHandling property of the JsonPolymorphicAttribute:

• JsonUnknownDerivedTypeHandling.FallBackToBaseType: If an unknown derived type is encountered, deserialization will fall back to creating an instance of the base type, discarding any properties specific to the unknown derived type.

• JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor: This option attempts to deserialize to the nearest declared derived type in the hierarchy. However, be cautious as this can lead to ambiguity in complex hierarchies (the "diamond" problem) and potentially throw exceptions.

• JsonUnknownDerivedTypeHandling.FailSerialization: This is the default behavior, where a NotSupportedException is thrown if an unknown derived type is encountered during serialization.

Configuring Polymorphism with the Contract Model

For scenarios where using attributes directly on your types is not feasible (e.g., working with large or third-party domain models), System.Text.Json provides a contract model approach. This involves creating a custom DefaultJsonTypeInfoResolver subclass where you can programmatically define the polymorphic configuration for your type hierarchies.

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

public class PolymorphicTypeResolver : DefaultJsonTypeInfoResolver
{
    public override JsonTypeInfo GetTypeInfo(Type type, JsonSerializerOptions options)
    {
        JsonTypeInfo jsonTypeInfo = base.GetTypeInfo(type, options);
        Type basePointType = typeof(BasePoint);
        if (jsonTypeInfo.Type == basePointType)
        {
            jsonTypeInfo.PolymorphismOptions = new JsonPolymorphismOptions
            {
                TypeDiscriminatorPropertyName = "$point-type",
                IgnoreUnrecognizedTypeDiscriminators = true,
                UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FailSerialization,
                DerivedTypes =
                {
                    new JsonDerivedType(typeof(ThreeDimensionalPoint), "3d"),
                    new JsonDerivedType(typeof(FourDimensionalPoint), "4d")
                }
            };
        }
        return jsonTypeInfo;
    }
}

public class BasePoint
{
    public int X { get; set; }
    public int Y { get; set; }
}

public class ThreeDimensionalPoint : BasePoint
{
    public int Z { get; set; }
}

public class FourDimensionalPoint : ThreeDimensionalPoint
{
    public int W { get; set; }
}

public class Program
{
    public static void Main(string[] args)
    {
        var options = new JsonSerializerOptions
        {
            TypeInfoResolver = new PolymorphicTypeResolver(),
            WriteIndented = true
        };

        BasePoint point = new FourDimensionalPoint { X = 1, Y = 2, Z = 3, W = 4 };
        string json = JsonSerializer.Serialize(point, options);
        Console.WriteLine(json);

        BasePoint? result = JsonSerializer.Deserialize<BasePoint>(json, options);
        Console.WriteLine(result?.GetType());
    }
}

In this example, the PolymorphicTypeResolver dynamically configures polymorphism for the BasePoint type, specifying the derived types and the type discriminator name.

Important Considerations

• Explicit Opt-in: For polymorphic serialization to work correctly, derived types must be explicitly opted into the process using JsonDerivedTypeAttribute or configured through the contract model. Undeclared types will generally lead to exceptions.
• Base Type Configuration: Polymorphic configurations set on derived types are not automatically inherited by base types. The base type needs to be configured independently.
• Supported Hierarchies: Polymorphism with type discriminators is supported for both interface and class hierarchies.
• Converter Limitations: Polymorphism using type discriminators relies on the default converters for objects, collections, and dictionary types. Custom converters might require specific handling for polymorphic scenarios.
• Source Generation: Polymorphism is supported in metadata-based source generation but not in fast-path source generation.
• Type of Serialized Value: Ensure that when serializing polymorphically, the declared type of the object being serialized (or the generic type parameter in Serialize<TValue>) is the polymorphic base type.

Conclusion

System.Text.Json provides robust mechanisms for handling polymorphic types in your .NET applications. By leveraging the JsonDerivedTypeAttribute and JsonPolymorphicAttribute, or by implementing custom contract resolvers, you can effectively serialize and deserialize complex type hierarchies while preserving type information. Understanding the nuances of type discriminators, handling unknown types, and adhering to the best practices outlined in this article will empower you to work confidently with polymorphic JSON data in your C# projects.