Discriminalizer 2.0.0

Discriminalizer

.NET library designed for seamless JSON deserialization of objects with complex discrimination requirements, built on top of System.Text.Json.

Motivation

In the realm of JSON deserialization, accommodating objects with intricate discrimination requirements can be challenging. While System.Text.Json provides robust support for basic deserialization tasks, handling complex discrimination logic often involves writing cumbersome and error-prone custom converters.

The library simplifies this process by offering a straightforward solution for deserializing JSON data into objects with complex discrimination needs. By extending System.Text.Json's functionality, we provide developers with a seamless way to deserialize JSON, even when dealing with intricate discrimination requirements.

With this library, developers can efficiently map JSON data to their object models without the need for extensive custom converter implementations. This simplifies the deserialization process, resulting in cleaner and more maintainable code.

Usage

Let's take for example a list of animals, where each animal can be either a wild or domestic animal. The animals can be of different types, such as dogs and cats. We want to deserialize this list into a collection of objects, where each object represents a specific animal type.

[
  {
    "Type": "Dog",
    "Origin": "Wild"
  },
  {
    "Type": "Dog",
    "Origin": "Domestic"
  },
  {
    "Type": "Cat",
    "Origin": "Wild"
  },
  {
    "Type": "Cat",
    "Origin": "Domestic"
  }
]

Next thing is to define the classes that represent the animals.

public class WildDog { }
public class DomesticDog { }
public class WildCat { }
public class DomesticCat { }

Now we can use the Discriminator class to configure the deserialization scheme. The Discriminator has a constructor that takes the names of the properties that will be used to determine the type of the object.

The With method is used to register the types that will be used to deserialize the objects. It take an array of property values, that will be used to determine if the JSON object represents the registered type.

Discriminator discriminator = new Discriminator("Type", "Origin")
    .With<WildDog>("Dog", "Wild")
    .With<DomesticDog>("Dog", "Domestic")
    .With<WildCat>("Cat", "Wild")
    .With<DomesticCat>("Cat", "Domestic");

Finally, we can use the discriminator to deserialize the JSON.

// Configure the deserialization options. You need to provide JsonSerializerOptions, a list of discriminators and
// a flag that indicates if "schemaless" objects should be deserialized as well. 
// Schemaless objects are objects without a coresponding class.
JsonOptions options = new JsonOptions().WithDiscriminator(discriminator);

// Deserialize a JSON string (variable is out of scope) to JsonNode using System.Text.Json.JsonSerializer.
JsonNode jsonNode = JsonSerializer.Deserialize<JsonNode>(jsonString);

// Deserialize JsonNode into matching list of objects.
IEnumerable<object> deserialized = await Json.Deserialize(jsonNode, options, CancellationToken.None);

// You can use the ".OfType<T>()" extension method to filter the objects by type.
WildDog dog = deserialized.OfType<WildDog>().Single();

Schemaless objects

If you want to deserialize objects that do not have a corresponding class, you need to enable it in the JsonOptions. The schemaless objects will be deserialized as IReadOnlyDictionary<string, object>.

IMPORTANT: This feature uses recursion to travel through the nested JSON objects, so it can cause StackOverflowException if an object is too deep. Unless you really need this feature and you are sure that there are not too many levels of nested objects, it is best to keep it disabled.

License

This project is licensed under the MIT License - see the LICENSE file for more details.