dotnet-json-polymorphic

Configure polymorphic JSON serialization using [JsonPolymorphic] and [JsonDerivedType] attributes for type-safe inheritance hierarchies.

When to Use

• •Serializing inheritance hierarchies with System.Text.Json
• •Adding type discriminators for polymorphic deserialization
• •Preparing polymorphic types for AOT-compatible JSON source generation
• •Replacing Newtonsoft.Json TypeNameHandling with modern attributes

Requirements

• •.NET 7 or higher

Steps

1. •

   Ask scope:

   • •Ask user: "Apply to entire solution or specific project?"
   • •If specific project, ask which project
2. •

   Search for existing [JsonPolymorphic] attributes:

   • •Detect existing project conventions
   • •Note any TypeDiscriminatorPropertyName values found
3. •

   Extract discriminator conventions:

   • •Search for TypeDiscriminatorPropertyName in existing attributes
   • •Record all unique discriminator property names found
4. •

   Find polymorphic candidates:

   • •Search for abstract classes with derived types
   • •Search for interfaces with implementing classes used in serialization
   • •Look for classes with virtual members that are inherited
5. •

   Ask about discriminator property name:

   • •If existing discriminators found, show them to user
   • •Ask: "What discriminator property name? (Default: $type, Found: [list existing])"
6. •

   Check for consistency:

   • •If multiple different discriminators found in codebase
   • •Ask: "Found multiple discriminators: [list]. Standardize to single value?"
7. •

   Apply attributes to base types:

   csharp

   [JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
   [JsonDerivedType(typeof(DerivedA), typeDiscriminator: "DerivedA")]
   [JsonDerivedType(typeof(DerivedB), typeDiscriminator: "DerivedB")]
   public abstract class BaseClass
   {
   }
   

   • •Use full type name as discriminator value (e.g., "WeatherForecastWithCity")
8. •

   Add using directive:

   • •Ensure using System.Text.Json.Serialization; is present
9. •

   Verify with build:

   bash

   dotnet build
   

10. •

    Report results:

    • •List all base types configured
    • •List all derived type mappings added
    • •Confirm build status

Example Conversion

Before:

public abstract class Notification
{
    public string Message { get; set; }
}

public class EmailNotification : Notification
{
    public string EmailAddress { get; set; }
}

public class SmsNotification : Notification
{
    public string PhoneNumber { get; set; }
}

After:

[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
[JsonDerivedType(typeof(EmailNotification), typeDiscriminator: "EmailNotification")]
[JsonDerivedType(typeof(SmsNotification), typeDiscriminator: "SmsNotification")]
public abstract class Notification
{
    public string Message { get; set; }
}

public class EmailNotification : Notification
{
    public string EmailAddress { get; set; }
}

public class SmsNotification : Notification
{
    public string PhoneNumber { get; set; }
}

JSON Output:

{
  "$type": "EmailNotification",
  "message": "Hello",
  "emailAddress": "user@example.com"
}

Notes

• •AOT Compatibility: Metadata-based source generation is supported; fast-path source generation is NOT supported for polymorphic types
• •Serialization requirement: Must serialize using the base type for polymorphism to work (e.g., JsonSerializer.Serialize<Notification>(emailNotification))
• •Discriminator values: String discriminators are recommended over integers for readability and forward compatibility
• •Nested hierarchies: Each level in the hierarchy needs its own [JsonPolymorphic] attribute if it has derived types
• •Interface support: Interfaces can also use [JsonPolymorphic] when they define the contract for serialization

Documentation

• •System.Text.Json Polymorphism