dotnet / dotnet/aspnetcore

Support C# unions

Open
#64,599 7 comments 47 reactions 1 assignee Claimed by @DeagleGross View on GitHub
area-blazor area-minimal area-signalr feature-json-patch feature-openapi on-roadmap
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 10h
Merged PRs (30d)
281

Description

C# is expected to add language-level union types, and we should prepare to support them end-to-end once the feature lands.

Impacted frameworks/tech: Minimal APIs, Blazor, SignalR, MVC, JSON Patch, OpenAPI

#### **Key Areas to Address**

* **Serialization handling**
Ensure C# unions work correctly as *both* input and result types. This includes JSON body serialization (STJ — see dotnet/runtime#127299), non-body parameter binding (query, route, header, form), and any polymorphic scenarios.

* **Polymorphism support**
Verify that unions interoperate smoothly with existing polymorphic type handling in the framework and serializers. Note that unions are **not** the same as `[JsonPolymorphic]` types — they have no discriminator on the wire by default and use structural matching.

* **OpenAPI integration**
Update OpenAPI generation so that union types are accurately represented in generated specs.

* **Source-generated & non-source-generated parity**
Confirm consistent behavior across both source-generated Minimal APIs (RDG) and the non-source-generated `RequestDelegateFactory` (RDF).
* **Non-body parameter binding**
Query, route, header, and form parameters of union type need a binding story that does **not** route through STJ. This includes structural matching for unambiguous cases and a classifier path for ambiguous ones.

#### **Goals**

Achieve seamless usage of C# unions across the API surface so developers can use them naturally — both with and without explicit discriminators — without workarounds.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.