Add a design document for System.Text.Json polymorphic serialization

[eiriktsarpalis]

Draft Implementation PR

[khellang]

This property name seems to suggest it's a collection of types? 🤔

[eiriktsarpalis]

I was having similar thoughts. What would be some suggested alternatives? SupportedPolymorphicTypesPredicate perhaps?

[layomia]

Why provide two models? Could we get away with just this one (non-generic)?

[eiriktsarpalis]

Having just the non-generic one should be sufficient, however the generic one is type-safe so users might appreciate having that option.

[FiniteReality]

Would users be able to specify the name of the discriminator field in the serialized model here? The examples use $type, but not all web APIs which use discriminated union-like types use that naming.

[FiniteReality]

Furthermore: are non-string values permitted? It's also often the case that web APIs use integers for these discriminator values, which would often be mapped to an enum in C# code.

[eiriktsarpalis]

Would users be able to specify the name of the discriminator field in the serialized model here? The examples use $type, but not all web APIs which use discriminated union-like types use that naming.

Yes, that is something we are considering although it has not been included in the prototype for now. There are a few infrastructural problems to be sorted out, for example our metadata parsing implementation currently requires that all metadata properties start with $ and are placed before any other properties in the object.

Furthermore: are non-string values permitted? It's also often the case that web APIs use integers for these discriminator values, which would often be mapped to an enum in C# code.

Not in the prototype, but you're making a good point that this should be supported. We would probably need to make the JsonKnownTypeAttribute accept object parameters but require that each type uses a unique identifier type, so the following configuration would be invalid:

[JsonKnownType(typeof(Bar), 1)]
[JsonKnownType(typeof(Baz), "baz")]
public class Foo {}

As far as supported identifier types go, am I right to assume that only string and int values should be accepted?

[FiniteReality]

for example our metadata parsing implementation currently requires that all metadata properties start with $ and are placed before any other properties in the object.

Yeah - in my own converters I've resorted to making a copy of the reader, finding and deserializing the discriminator, and then using the reader copy to deserialize as the actual type, updating the original reader with the copy after the fact. While this fixes the "must be the first field in the JSON object" issue, it's not that great because it parses the value multiple times.

As far as supported identifier types go, am I right to assume that only string and int values should be accepted?

As far as I'm aware, yes, only string and int are used for these. However, I think it may be convenient to support enum types too, as they're easily converted to int, and are (IMO) the natural type to use for a discriminator.

[eiriktsarpalis]

I've split this design document into to separate API proposals in the relevant issues: dotnet/runtime#29937 and dotnet/runtime#30083.