jsonsubtypes

To map specific discriminator values to specific subtypes, use the [JsonSubtypes.KnownSubType] attribute on the base class. This works with various value types, including string, enum, or int.

Example: Mapping a Sound property to Dog or Cat subtypes.

[JsonConverter(typeof(JsonSubtypes), "Sound")]
[JsonSubtypes.KnownSubType(typeof(Dog), "Bark")]
[JsonSubtypes.KnownSubType(typeof(Cat), "Meow")]
public class Animal
{
    public virtual string Sound { get; }
    public string Color { get; set; }
}

public class Dog : Animal
{
    public override string Sound { get; } = "Bark";
    public string Breed { get; set; }
}

public class Cat : Animal
{
    public override string Sound { get; } = "Meow";
    public bool Declawed { get; set; }
}

// Usage
var animal = JsonConvert.DeserializeObject<Animal>("{\"Sound\":\"Bark\",\"Breed\":\"Jack Russell Terrier\"}");

You can use the [JsonConverter] attribute on a base type or interface to specify which JSON property contains the type discriminator. The second parameter of the attribute defines the name of this property.

Note: This approach requires that subtypes are in the same assembly as the base type and are either in the same namespace or use a fully qualified type name.

[JsonConverter(typeof(JsonSubtypes), "Kind")]
public interface IAnimal
{
    string Kind { get; }
}

public class Dog : IAnimal
{
    public string Kind { get; } = "Dog";
    public string Breed { get; set; }
}

public class Cat : IAnimal {
    public string Kind { get; } = "Cat";
    public bool Declawed { get; set;}
}

// Usage
var animal = JsonConvert.DeserializeObject<IAnimal>("{\"Kind\":\"Dog\",\"Breed\":\"Jack Russell Terrier\"}");

If the type discriminator property is not present in your C# class hierarchy (it only exists in the JSON), you must register the converter explicitly in JsonSerializerSettings using JsonSubtypesConverterBuilder.

To ensure the discriminator is included during serialization, you must call .SerializeDiscriminatorProperty() in the builder chain.

var settings = new JsonSerializerSettings();
settings.Converters.Add(JsonSubtypesConverterBuilder
    .Of(typeof(Animal), "Type") // type property is only defined in JSON
    .RegisterSubtype(typeof(Cat), AnimalType.Cat)
    .RegisterSubtype(typeof(Dog), AnimalType.Dog)
    .SerializeDiscriminatorProperty() // ask to serialize the type property
    .Build());

You can determine a subtype based on whether a specific property is present in the JSON object, rather than relying on a dedicated discriminator field.

This can be achieved via attributes using [JsonSubtypes.KnownSubTypeWithProperty] or via code configuration using JsonSubtypesWithPropertyConverterBuilder.

Attribute approach:

[JsonConverter(typeof(JsonSubtypes))]
[JsonSubtypes.KnownSubTypeWithProperty(typeof(Employee), "JobTitle")]
[JsonSubtypes.KnownSubTypeWithProperty(typeof(Artist), "Skill")]
public class Person { ... }

// Code configuration approach
settings.Converters.Add(JsonSubtypesWithPropertyConverterBuilder
    .Of(typeof(Person))
    .RegisterSubtypeWithProperty(typeof(Employee), "JobTitle")
    .RegisterSubtypeWithProperty(typeof(Artist), "Skill")
    .Build());

A builder used to configure converters that determine subtypes based on the presence of specific properties in the JSON, rather than a discriminator value.

Methods:

• Of(Type baseType): Sets the base type.
• Of<T>(): Generic version of Of.
• RegisterSubtypeWithProperty(Type subtype, string propertyName): Maps a subtype to the presence of a specific JSON property.
• RegisterSubtypeWithProperty<T>(string propertyName): Generic version of RegisterSubtypeWithProperty.
• SetFallbackSubtype(Type fallbackType): Defines which type to instantiate if no property matches.
• Build(): Returns the configured converter instance.