Add System.Text.Json support for F# discriminated unions

[eiriktsarpalis]

System.Text.Json: Add support for F# discriminated unions

Fixes #55744

Summary

Adds JSON serialization and deserialization support for F# discriminated unions to System.Text.Json. This is the last remaining F# type that was not supported by STJ.

Serialization Format

Fieldless union cases serialize as JSON strings. Cases with fields serialize as JSON objects with a $type type discriminator property:

type Shape =
    | Point
    | Circle of radius: float
    | Rectangle of height: float * length: float

F# Value	JSON
Point	"Point"
Circle 3.14	{"$type":"Circle","radius":3.14}
Rectangle(10.0, 20.0)	{"$type":"Rectangle","height":10,"length":20}

Both forms are accepted on deserialization: "Point" and {"$type":"Point"} are equivalent for fieldless cases.

Features

• Class and struct unions are both supported.
• Recursive unions (e.g. tree types) work via lazy converter resolution.
• PropertyNamingPolicy applies to both case discriminator names and field names.
• PropertyNameCaseInsensitive applies to both case names and field names during deserialization.
• JsonPropertyNameAttribute on union cases overrides the discriminator name (takes precedence over naming policy).
• Custom discriminator property name via [<JsonPolymorphic(TypeDiscriminatorPropertyName = "kind")>] on the union type.
• AllowOutOfOrderMetadataProperties — the $type discriminator does not need to be the first property.
• RespectRequiredConstructorParameters — when enabled, all union case fields are treated as required (matching F# record behavior). When disabled, missing fields default to default(T).
• String form tolerance — "Circle" is accepted for cases with fields when RespectRequiredConstructorParameters is off (constructs with all-default field values).

Examples

open System.Text.Json
open System.Text.Json.Serialization

// Basic serialization
let json = JsonSerializer.Serialize(Circle 3.14)
// -> {"$type":"Circle","radius":3.14}

let shape = JsonSerializer.Deserialize<Shape>(json)
// -> Circle 3.14

// With naming policy
let options = JsonSerializerOptions(PropertyNamingPolicy = JsonNamingPolicy.CamelCase)
let json2 = JsonSerializer.Serialize(Circle 3.14, options)
// -> {"$type":"circle","radius":3.14}

// Custom discriminator
[<JsonPolymorphic(TypeDiscriminatorPropertyName = "kind")>]
type MyUnion = Alpha | Beta of x: int

let json3 = JsonSerializer.Serialize(Beta 42)
// -> {"kind":"Beta","x":42}

// Out-of-order discriminator
let options2 = JsonSerializerOptions(AllowOutOfOrderMetadataProperties = true)
let result = JsonSerializer.Deserialize<Shape>("""{"radius":3.14,"$type":"Circle"}""", options2)
// -> Circle 3.14

Reflection-only

This feature works exclusively with the reflection-based serializer. It does not work with:

• C# source generators (JsonSourceGenerationOptions / JsonSerializerContext) — the source generator does not emit metadata for F# union types. Attempting to include an F# union type in a source-generated context will produce a compile-time error or fall back to the default object serialization.
• Native AOT — because the implementation relies on reflection (FSharp.Core reflection APIs for reading union case metadata, Func<object[], object> constructors, and Func<object, object[]> field readers), it requires the RequiresUnreferencedCode and RequiresDynamicCode code paths. F# unions will not serialize correctly in trimmed or AOT-compiled applications.

Implementation

• FSharpUnionConverter<T> — a JsonConverter<T> with ConverterStrategy.Value that handles both string and object JSON forms.
• FSharpCoreReflectionProxy — extended with union case metadata extraction (FSharpUnionCaseInfo, tag readers, constructors, field readers).
• FSharpTypeConverterFactory — updated to detect union types and create the converter, reading [JsonPolymorphic] for custom discriminator names.
• Field count per union case is limited to 64 (bitmask-based required field tracking).
• No new public API surface.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

---

You can also share your feedback on Copilot code review. Take the survey.