JsonSubTypes

Discriminated Json Subtypes Converter implementation for .NET

JsonSubTypes

JsonSubTypes is a discriminated Json sub-type Converter implementation for .NET

CI CodeQL Code Coverage Quality Gate Status NuGet NuGet CodeFactor FOSSA Status

Which package? State and choices

JsonSubTypes exists in two packages that share the same API and registration model (attributes and JsonSubtypesConverterBuilder):

The examples below use the Newtonsoft.Json package; the API is the same for System.Text.Json, so read them either way. If you are targeting System.Text.Json, then after these examples jump to the System.Text.Json variant section, which explains the engines available there (Build() converter, BuildResolver(), AOT generator) and their differences and limitations.

Security: unless a subtype mapping is explicitly declared, the converter resolves subtypes by name from the JSON discriminator (only types assignable from the base are considered). See the security section before exposing a name-based hierarchy to untrusted JSON.

DeserializeObject with custom type property 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;}
}

The second parameter of the JsonConverter attribute is the JSON property name that will be use to retreive the type information from JSON.

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

N.B.: This only works for types in the same assembly as the base type/interface and either in the same namespace or with a fully qualified type name.

DeserializeObject with custom type mapping

[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; }
}

var animal = JsonConvert.DeserializeObject<IAnimal>("{\"Sound\":\"Bark\",\"Breed\":\"Jack Russell Terrier\"}");
Assert.AreEqual("Jack Russell Terrier", (animal as Dog)?.Breed);

N.B.: Also works with other kind of value than string, i.e.: enums, int, …

SerializeObject and DeserializeObject with custom type property only present in JSON

This mode of operation only works when JsonSubTypes is explicitely registered in JSON.NET’s serializer settings, and not through the [JsonConverter] attribute.

public abstract class Animal
{
    public int Age { get; set; }
}

public class Dog : Animal
{
    public bool CanBark { get; set; } = true;
}

public class Cat : Animal
{
    public int Lives { get; set; } = 7;
}

public enum AnimalType
{
    Dog = 1,
    Cat = 2
}

Registration:

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

or using syntax with generics:

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

De-/Serialization:

var cat = new Cat { Age = 11, Lives = 6 }

var json = JsonConvert.SerializeObject(cat, settings);

Assert.Equal("{\"Lives\":6,\"Age\":11,\"Type\":2}", json);

var result = JsonConvert.DeserializeObject<Animal>(json, settings);

Assert.Equal(typeof(Cat), result.GetType());
Assert.Equal(11, result.Age);
Assert.Equal(6, (result as Cat)?.Lives);

DeserializeObject mapping by property presence

[JsonConverter(typeof(JsonSubtypes))]
[JsonSubtypes.KnownSubTypeWithProperty(typeof(Employee), "JobTitle")]
[JsonSubtypes.KnownSubTypeWithProperty(typeof(Artist), "Skill")]
public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

public class Employee : Person
{
    public string Department { get; set; }
    public string JobTitle { get; set; }
}

public class Artist : Person
{
    public string Skill { get; set; }
}

or using syntax with generics:

string json = "[{\"Department\":\"Department1\",\"JobTitle\":\"JobTitle1\",\"FirstName\":\"FirstName1\",\"LastName\":\"LastName1\"}," +
                "{\"Department\":\"Department1\",\"JobTitle\":\"JobTitle1\",\"FirstName\":\"FirstName1\",\"LastName\":\"LastName1\"}," +
                "{\"Skill\":\"Painter\",\"FirstName\":\"FirstName1\",\"LastName\":\"LastName1\"}]";


var persons = JsonConvert.DeserializeObject<IReadOnlyCollection<Person>>(json);
Assert.AreEqual("Painter", (persons.Last() as Artist)?.Skill);

Registration:

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

or

settings.Converters.Add(JsonSubtypesWithPropertyConverterBuilder
    .Of<Person>()
    .RegisterSubtypeWithProperty<Employee>("JobTitle")
    .RegisterSubtypeWithProperty<Artist>("Skill")
    .Build());

A default class other than the base type can be defined

[JsonConverter(typeof(JsonSubtypes))]
[JsonSubtypes.KnownSubType(typeof(ConstantExpression), "Constant")]
[JsonSubtypes.FallBackSubType(typeof(UnknownExpression))]
public interface IExpression
{
    string Type { get; }
}

Or with code configuration:

settings.Converters.Add(JsonSubtypesConverterBuilder
    .Of(typeof(IExpression), "Type")
    .SetFallbackSubtype(typeof(UnknownExpression))
    .RegisterSubtype(typeof(ConstantExpression), "Constant")
    .Build());

settings.Converters.Add(JsonSubtypesWithPropertyConverterBuilder
    .Of(typeof(IExpression))
    .SetFallbackSubtype(typeof(UnknownExpression))
    .RegisterSubtype(typeof(ConstantExpression), "Value")
    .Build());

System.Text.Json variant

Status: experimental. The JsonSubTypes.Text.Json package is a release candidate (1.0.0-rc.x) and not yet part of the project’s stable offering. The code is fully tested (133 unit tests) and the API is complete, but the stable 1.0.0 release will follow once the package has been exercised in more real-world projects.

A variant of the library for System.Text.Json (.NET 8+) is available in the JsonSubTypes.Text.Json namespace and package. It supports the same attribute-driven and builder-driven API, adapted to System.Text.Json idioms.

Attribute based discriminator

using JsonSubTypes.Text.Json;

[JsonSubTypeConverter(typeof(JsonSubtypes<Animal>), "Sound")]
[KnownSubType(typeof(Dog), "Bark")]
[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; }
}

var animal = JsonSerializer.Deserialize<Animal>("{\"Sound\":\"Bark\",\"Breed\":\"Jack Russell Terrier\"}");
Assert.AreEqual("Jack Russell Terrier", (animal as Dog)?.Breed);

Like the native [JsonDerivedType] polymorphism, the attribute-based converter handles both directions: serializing through the base type writes the discriminator, and deserialization reads it back, so round-trips work out of the box:

var json = JsonSerializer.Serialize<Animal>(new Dog { Breed = "Jack Russell Terrier" });
// {"Sound":"Bark","Breed":"Jack Russell Terrier"}
var back = JsonSerializer.Deserialize<Animal>(json);
Assert.IsInstanceOf<Dog>(back);

When the runtime type is not declared in the [KnownSubType] mappings (e.g. a multi-level hierarchy where the leaf is registered on an intermediate base), serialization falls back to the plain runtime-type contract without a discriminator.

Builder based dynamic registration

var options = new JsonSerializerOptions();
options.Converters.Add(JsonSubtypesConverterBuilder
    .Of(typeof(Animal), "type")
    .RegisterSubtype(typeof(Cat), AnimalType.Cat)
    .RegisterSubtype(typeof(Dog), AnimalType.Dog)
    .Build());

var result = JsonSerializer.Deserialize<Animal>("{\"catLives\":6,\"type\":2,\"age\":11}", options);
Assert.AreEqual(typeof(Cat), result.GetType());

Native resolver via BuildResolver()

JsonSubtypesConverterBuilder also exposes the native System.Text.Json polymorphic contract model (JsonPolymorphismOptions) as an alternative to Build(). Assign the result to JsonSerializerOptions.TypeInfoResolver instead of Converters:

var options = new JsonSerializerOptions
{
    TypeInfoResolver = JsonSubtypesConverterBuilder
        .Of(typeof(Animal), "type")
        .RegisterSubtype(typeof(Cat), AnimalType.Cat)
        .RegisterSubtype(typeof(Dog), AnimalType.Dog)
        .SerializeDiscriminatorProperty()
        .BuildResolver()
};

The resolver delegates all serialization work to System.Text.Json, so it only supports a subset of the converter configuration and throws at build time otherwise: string or int discriminator values, a single level of hierarchy per base type, and the discriminator always written first. The following native behaviors are exposed as opt-in builder methods:

For several base type hierarchies, combine builders with JsonSubtypesConverterBuilder.BuildResolvers(...). Combining resolvers through JsonSerializerOptions.TypeInfoResolverChain does not work, because each resolver answers for every type and only the first one would be applied.

Serializing the discriminator

The attribute-based converter writes the discriminator by default. For the builder, writing the discriminator is opt-in, like the Newtonsoft version:

options.Converters.Add(JsonSubtypesConverterBuilder
    .Of(typeof(Animal), "type")
    .SerializeDiscriminatorProperty()                 // discriminator first (default)
    // or .SerializeDiscriminatorProperty(false)      // discriminator last
    .RegisterSubtype(typeof(Cat), AnimalType.Cat)
    .RegisterSubtype(typeof(Dog), AnimalType.Dog)
    .Build());

var json = JsonSerializer.Serialize<Animal>(new Cat { Age = 11, Lives = 6 }, options);
// {"type":2,"catLives":6,"age":11}

As with the native [JsonDerivedType] polymorphism, serialization must go through the base type (or a base-typed property/collection) for the converter and the discriminator to apply. Serializing a value with a concrete subtype as its static type bypasses the converter, and serializing an unregistered type throws when SerializeDiscriminatorProperty() is used.

Mapping by property presence

[JsonSubTypeConverter(typeof(JsonSubtypes<Person>))]
[KnownSubTypeWithProperty(typeof(Employee), "JobTitle")]
[KnownSubTypeWithProperty(typeof(Artist), "Skill")]
public class Person { }

Fallback subtype

[JsonSubTypeConverter(typeof(JsonSubtypes<IExpression>), "Type")]
[KnownSubType(typeof(ConstantExpression), "Constant")]
[FallBackSubType(typeof(UnknownExpression))]
public interface IExpression { }

Differences with the Newtonsoft.Json version

Security

When a subtype is resolved by name — which happens for both packages only when no subtype mapping is declared at all (no [KnownSubType] attribute, no RegisterSubtype builder call) — the converter turns the JSON discriminator string into a type name and instantiates the matching type. Declaring a mapping at all switches the converter to that mapping, even when no entry matches; the name-based path is never used then.

Only types assignable from the polymorphic base type can be resolved, but any such type present in the base type’s assembly (for Newtonsoft.Json) or in that assembly plus any assembly registered via JsonSubTypesTypeResolution (for System.Text.Json) can be instantiated with attacker-controlled JSON. Do not expose a name-based hierarchy to untrusted JSON without validating the payload upstream; prefer explicit [KnownSubType] or builder mappings whenever the discriminator can come from outside your own code.

Which engine should I use?

JsonSubTypes.Text.Json ships three engines that share the same configuration layer (the attributes and JsonSubtypesConverterBuilder), and a parity test battery keeps them aligned:

Feature / Capability Native STJ ([JsonDerivedType]) Resolver (BuildResolver()) Converter (Build()) Generator (JsonSubTypes.Text.Json.Aot)
Type discriminator mapping (string/int) ✅ ✅ ✅ ✅
Enum / null discriminator values ❌ ❌ ✅ ✅
Custom discriminator property name ✅ ✅ ✅ ✅
Property presence matching (KnownSubTypeWithProperty) ❌ ❌ ✅ ✅
Fallback subtype (FallBackSubType) ❌ base only ✅ ✅
Discriminator written last ❌ ❌ ✅ ✅
Naming policy / case-insensitive on the discriminator name ❌ ⚠️ ✅ ✅
Dotted / nested discriminator path ("nested.type") ❌ ❌ ✅ ✅
Nested (multi-level) hierarchies ⚠️ ❌ ✅ ✅
Dynamic subtype registration at runtime ❌ ❌ ✅ ✅ (runtime map)
Custom type-name resolution hook ❌ ❌ ✅ (built-in) ✅ (hook)
Cross-assembly / plugin types outside the compilation ❌ ❌ ✅ ⚠️ (must be in the source-gen context)
Native AOT / Trimming support ✅ ❌ ❌ ✅

The three engines in one line:

  1. Converter (Build()) — the full-featured runtime engine and the right default for non-AOT applications.
  2. Resolver (BuildResolver()) — the thin native bridge: simplest and fastest, but limited to the subset the native contract model can express.
  3. Generator (JsonSubTypes.Text.Json.Aot) — a Roslyn source generator emitting compiled converters: the Native AOT answer, with routing compiled instead of reflected.

The decisive difference is not speed, it is when the hierarchy is known:

  Converter (Build()) Generator (JsonSubTypes.Text.Json.Aot)
Subtypes known at compile time (attributes on your own types) ✅ ✅
Subtypes known only at runtime (plugins, loaded assemblies, config) ✅ ✅ (via RegisterDynamicSubtype / resolver hooks)
Subtypes in third-party assemblies you cannot annotate ✅ (builder, no attribute needed) ❌ (generator only sees the source-gen context)

The generator reads its registrations from [JsonSubTypesAotConverter]/[KnownSubType]-style attributes at compile time (JsonSubTypesGenerator.cs). It can only route types visible to the compilation it runs in. The converter’s Build() accepts a runtime registration through the builder, so it is the only engine that can handle hierarchies whose subtypes are discovered at runtime — plugins, assemblies loaded dynamically, or types you do not own. The generator is the better fit when the hierarchy is fixed and known at build time, and the only engine compatible with trimming/Native AOT.

Converter known scope & fallback path

To preserve full compatibility with advanced features while delegating object serialization to System.Text.Json, the converter isolates base-type serialization to a narrow path (when serializing the base type directly or reading an unregistered fallback type):

Performance (measured)

Benchmarked with BenchmarkDotNet (JsonSubTypes.Benchmarks, .NET 10); the methodology, machine and full result tables are in PERFORMANCE.md. In short:

Reproduce the measurements yourself with dotnet run -c Release --project JsonSubTypes.Benchmarks -- --filter "*" (a native compiler is needed for the Native AOT job; see PERFORMANCE.md).

Decision matrix

| Use case | Recommended | |—|—| | Native AOT / trimming, hierarchy known at compile time | JsonSubTypes.Text.Json.Aot generator | | Non-AOT, full feature set with minimal setup | Converter (Build()) | | Non-AOT, string/int discriminators only, fastest and simplest | Resolver (BuildResolver()) | | Discriminator by property presence (no discriminator field in the JSON) | Converter or Generator | | Open hierarchies / subtypes registered at runtime | Converter, or Generator (RegisterDynamicSubtype) | | Non string/int discriminator values (enums, null) | Converter or Generator | | Nested or dotted discriminator paths (e.g. "nested.property") | Converter or Generator | | Resolution by arbitrary .NET type name / cross-assembly plugins | Converter (built-in), or Generator (CustomTypeNameResolver hook) | | Migrating an existing JsonSubTypes/Newtonsoft code base | Converter (same API) |

Native AOT

The resolver and the converter rely on reflection and are therefore not compatible with trimming or Native AOT. The polymorphic metadata that the resolver configures must be declared at compile time for AOT: System.Text.Json freezes it at build time, and a source-generated JsonTypeInfo is read-only at runtime. Assigning PolymorphismOptions to a source-generated JsonTypeInfo throws InvalidOperationException on both .NET 8 and .NET 10.

For Native AOT, the JsonSubTypes.Text.Json.Aot generator compiles the routing into the converter (verified to run as a native binary with dotnet publish -r linux-x64 -p:PublishAot=true). The generator is referenced as an analyzer and reads its attributes ([JsonSubTypesAotConverter], [KnownSubType], …) from the JsonSubTypes.Text.Json package, so reference both JsonSubTypes.Text.Json.Aot and JsonSubTypes.Text.Json:

dotnet add package JsonSubTypes.Text.Json.Aot
dotnet add package JsonSubTypes.Text.Json

Alternatively, declare the hierarchy with [JsonDerivedType] on the base type and use a plain source-generated context:

[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
[JsonDerivedType(typeof(Circle), "circle")]
[JsonDerivedType(typeof(Square), "square")]
public class Shape { }

[JsonSerializable(typeof(Shape))]
[JsonSerializable(typeof(Circle))]
[JsonSerializable(typeof(Square))]
public partial class ShapeJsonContext : JsonSerializerContext { }

var options = new JsonSerializerOptions { TypeInfoResolver = ShapeJsonContext.Default };
var json = JsonSerializer.Serialize<Shape>(new Circle { Radius = 2 }, options);
// {"$type":"circle","Radius":2}

💖 Support this project

If this project helped you save money or time or simply makes your life also easier, you can give me a cup of coffee =)

License

FOSSA Status