[API Proposal]: JsonDerivedType add ability to rename type discriminator

Start by reviewing the JsonDerivedTypeAttribute constructors and properties described in the API proposal, then trace how type discriminators are handled during serialization and deserialization. Done means a renamed derived type serializes with its current discriminator while old discriminator values remain accepted, with tests covering both string and integer discriminators.

Background and motivation

I would like to rename the type discriminator of a type.

A class in code may change of time, and currently if you simply changed the type discriminator you would break de-serializing of old json files.

e.g. you have this classes

[JsonDerivedType(typeof(DerivedClass1), "derivedClass1")]
[JsonDerivedType(typeof(Foo), "foo")]
public abstract class BaseClass
{

}

public class DerivedClass1 : BaseClass
{

}

public class Foo : BaseClass
{

}

and you want to rename Foo to Bar, if you don't want backward compatiblity with old json files all you have to do is this

[JsonDerivedType(typeof(DerivedClass1), "derivedClass1")]
//renamed typeof(Foo) to typeof(Bar)
//adjusted the type discriminator to bar
[JsonDerivedType(typeof(Bar), "bar")]
public abstract class BaseClass
{

}

public class DerivedClass1 : BaseClass
{

}

//renamed class Foo to Bar
public class Bar : BaseClass
{

}

but this breaks any old json files as they will still have $type: "Foo" and have no knowledge that it was renamed.

API Proposal

Extend the JsonDerivedType with a new property

    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface, AllowMultiple = true, Inherited = false)]
    public class JsonDerivedTypeAttribute : JsonAttribute
    {
        public JsonDerivedTypeAttribute(Type derivedType)
        {
            DerivedType = derivedType;
        }

        public JsonDerivedTypeAttribute(Type derivedType, string typeDiscriminator, string?[] oldTypeDiscriminator = null)
        {
            DerivedType = derivedType;
            TypeDiscriminator = typeDiscriminator;
            OldTypeDiscriminator = oldTypeDiscriminator;
        }
        public JsonDerivedTypeAttribute(Type derivedType, int typeDiscriminator, int?[] oldTypeDiscriminator = null)
        {
            DerivedType = derivedType;
            TypeDiscriminator = typeDiscriminator;
            OldTypeDiscriminator = oldTypeDiscriminator;
        }

        public Type DerivedType { get; }
        public object? TypeDiscriminator { get; }
        public object[]? OldTypeDiscriminator { get; }
    }

OR

Change type of TypeDiscriminator from object? to object[]?
though this would be a breaking change so maybe the first proposal is the more ideal

API Usage

[JsonDerivedType(typeof(DerivedClass1), "derivedClass1")]
//added the array with the old name
[JsonDerivedType(typeof(Bar), "bar", ["foo"])]
public abstract class BaseClass
{

}

On Serializing it should use JsonDerivedTypeAttribute's TypeDiscriminator property.
On De-Serializing it should check if $type matches either JsonDerivedTypeAttribute's TypeDiscriminator property OR the new introduced array OldTypeDiscriminator.

Alternative Designs

No response

Risks

No response