Document System.Text.Json features in .NET 11

[eiriktsarpalis]

Summary

Documents the 15 System.Text.Json work items tracked by #55465. The change adds a conceptual article for C# union serialization, expands polymorphism and source-generation guidance, updates the supported-type and customization references, and completes the .NET 11 library highlights.

Fixes #55465

Content source breakdown

Documentation area	Implementation sources	Treatment
C# union serialization and classifiers	dotnet/runtime#128162, #128900, #131797, #131879, and #132411	New conceptual article. Union and classifier examples are adapted from runtime tests. The model-choice section adapts the ASP.NET Core union and closed-hierarchy discussion; its Event example is newly generated and was verified on .NET 11 RC1 ({"$type":"Created","Id":42}). The Web-default quoted-number caveat adapts the blog's union-deserialization discussion. The JsonSchemaExporter anyOf note is newly generated from runtime tests and .NET 11 RC1 output, not from the blog's ASP.NET Core OpenAPI examples. No prose was copied verbatim.
JSON Lines serialization	dotnet/runtime#127567	Adapted into the supported-types article and What's New. The LF, indentation, Stream, and PipeWriter behavior follows the implementation tests.
F# discriminated unions	dotnet/runtime#125610	Adapted into supported-types, reflection/source-generation guidance, and What's New. The wire-format example follows the runtime test shape.
Closed-hierarchy inference	dotnet/runtime#130808 and #131623	New polymorphism guidance based on the API proposals and reflection/source-generation tests.
Inaccessible source-generated members	dotnet/runtime#124650, #126507, and #130163	Existing source-generation and immutability guidance updated for the final .NET 11 behavior.
Naming policies	dotnet/runtime#124645 and #124644	New type/member attribute guidance and PascalCase reference entry, adapted from API proposal examples.
Type-level ignore conditions	dotnet/runtime#124646	New section in the ignore-properties article, including precedence and invalid configuration behavior.
Open generic polymorphism	dotnet/runtime#127318	New C# and Visual Basic examples and supported/unsupported resolution guidance adapted from runtime tests.
New numeric converters	dotnet/runtime#131523	New supported-type and JSON Schema guidance for BFloat16, Decimal32, Decimal64, and Decimal128.
Open generic converters	dotnet/runtime#123209	Existing converter guidance checked and refined; the .NET 11 highlights now link to it.
By-reference constructors	dotnet/runtime#122950	New constructor-binding table and C#/Visual Basic examples adapted from reflection and source-generator tests.
Extension data	dotnet/runtime#120636 and #122838	Existing overflow guidance updated for IReadOnlyDictionary materialization and JsonObject flattening.
IReadOnlySet<T>	dotnet/runtime#120306	Added to the supported collection table and corrected in What's New.
Generic type metadata lookup	dotnet/runtime#123940	New strongly typed contract-metadata guidance and updated What's New sample.
Utf8JsonWriter.Reset options	dotnet/runtime#126578	New writer-reuse guidance and updated executable sample.

Expert review notes

All modified Markdown identifies the work as ai-assisted.

The new union article, structural-classifier behavior, closed-hierarchy RC1 APIs, and new numeric converters warrant focused API-owner review. The locally available .NET 11 Preview 7 SDK predates some of those merged/backported APIs, so their descriptions and examples were checked against the corresponding runtime tests and API proposals rather than executed against that SDK. The union, polymorphism, naming, ignore, extension-data, collection, metadata, writer, JSONL, C#, Visual Basic, and F# examples that Preview 7 contains were compiled or executed locally.

Validation

• Markdownlint: 15 changed Markdown files, 0 issues.
• Local relative links and snippet paths: 15 files validated.
• docs/core/whats-new/dotnet-11/snippets/csharp/snippets.csproj: build succeeded with .NET SDK 11.0.100-preview.7 and 0 warnings.
• Standalone C# verification covered transparent union JSON, closed and open-generic polymorphism, naming and ignore precedence, extension data, IReadOnlySet<T>, generic metadata lookup, writer reset, by-reference constructors, and JSON Lines output.
• Standalone Visual Basic verification covered naming and ignore attributes, writer reset, and open-generic polymorphism.
• Standalone F# verification produced "Point" and {"$type":"Circle","radius":3.14} for the documented discriminated union.
• git diff --check completed without errors.

---

Internal previews

Toggle expand/collapse

File	Preview link
docs/core/whats-new/dotnet-11/libraries.md	Learn preview
docs/core/whats-new/dotnet-11/overview.md	Learn preview
docs/core/whats-new/dotnet-11/snippets/csharp/Libraries.cs	Learn preview
docs/fundamentals/toc.yml	Learn preview
docs/standard/serialization/system-text-json/converters-how-to.md	Learn preview
docs/standard/serialization/system-text-json/custom-contracts.md	Learn preview
docs/standard/serialization/system-text-json/customize-properties.md	Learn preview
docs/standard/serialization/system-text-json/extract-schema.md	Learn preview
docs/standard/serialization/system-text-json/handle-overflow.md	Learn preview
docs/standard/serialization/system-text-json/ignore-properties.md	Learn preview
docs/standard/serialization/system-text-json/immutability.md	Learn preview
docs/standard/serialization/system-text-json/polymorphism.md	Learn preview
docs/standard/serialization/system-text-json/reflection-vs-source-generation.md	Learn preview
docs/standard/serialization/system-text-json/snippets/converters-how-to/csharp/OpenGenericConverter.cs	Learn preview
docs/standard/serialization/system-text-json/source-generation-modes.md	Learn preview
docs/standard/serialization/system-text-json/supported-types.md	Learn preview
docs/standard/serialization/system-text-json/union-types.md	Learn preview
docs/standard/serialization/system-text-json/use-utf8jsonwriter.md	Learn preview

Build report

[Copilot]

Pull request overview

This pull request updates System.Text.Json documentation for .NET 11 by adding new conceptual coverage (notably C# union serialization) and refreshing several existing articles and .NET 11 “What’s new” content to reflect new APIs and behaviors.

Changes:

• Adds a new conceptual article that documents C# union serialization and customization.
• Updates existing System.Text.Json guidance to cover .NET 11 features across polymorphism, source generation, supported types, naming, ignore behavior, schema export, extension data, and writer reuse.
• Updates .NET 11 library highlights content, navigation, and snippets to reference and demonstrate the new features.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/standard/serialization/system-text-json/use-utf8jsonwriter.md	Adds writer reuse guidance via Utf8JsonWriter.Reset(...) and AI usage frontmatter.
docs/standard/serialization/system-text-json/union-types.md	New article describing C# union serialization, classification, and source generation.
docs/standard/serialization/system-text-json/supported-types.md	Expands supported types coverage (JSON Lines, IReadOnlySet<T>, numeric types, and F# DU notes) and updates wording.
docs/standard/serialization/system-text-json/source-generation-modes.md	Updates source-generation guidance for non-public members/constructors and clarifies fast-path limitations.
docs/standard/serialization/system-text-json/reflection-vs-source-generation.md	Refreshes comparison text and adds a note about F# discriminated unions being reflection-only.
docs/standard/serialization/system-text-json/polymorphism.md	Adds closed-hierarchy inference guidance and open generic derived-type registration guidance.
docs/standard/serialization/system-text-json/immutability.md	Updates constructor binding guidance (including by-ref parameters, init-only behavior, and non-public support).
docs/standard/serialization/system-text-json/ignore-properties.md	Adds new section documenting type-level ignore conditions and precedence rules.
docs/standard/serialization/system-text-json/handle-overflow.md	Updates extension-data guidance (including IReadOnlyDictionary materialization and JsonObject flattening).
docs/standard/serialization/system-text-json/extract-schema.md	Updates schema exporter doc and adds new numeric converter/schema notes.
docs/standard/serialization/system-text-json/customize-properties.md	Adds PascalCase policy entry and documents per-type/member naming policy via attribute.
docs/standard/serialization/system-text-json/custom-contracts.md	Adds strongly typed GetTypeInfo<T>/TryGetTypeInfo<T> guidance and references union contract kind.
docs/standard/serialization/system-text-json/converters-how-to.md	Updates open generic converter guidance and clarifies behavior/error notes.
docs/fundamentals/toc.yml	Adds navigation entry for the new “Serialize union types” article.
docs/core/whats-new/dotnet-11/snippets/csharp/Libraries.cs	Updates/extends .NET 11 snippet code to match new features and examples.
docs/core/whats-new/dotnet-11/overview.md	Updates the .NET 11 overview bullet for System.Text.Json improvements.
docs/core/whats-new/dotnet-11/libraries.md	Reworks the System.Text.Json improvements section to align with the expanded .NET 11 documentation set.

Suppressed comments (2)

docs/standard/serialization/system-text-json/polymorphism.md:610

• This open-generic polymorphism example declares Base<T> and Derived<T> using semicolon-terminated class declarations, which doesn't compile. Use empty bodies ({ }) for the type declarations.

[JsonDerivedType(typeof(Derived<>), "derived")]
public class Base<T>;
public class Derived<T> : Base<T>;

docs/standard/serialization/system-text-json/supported-types.md:134

• This heading uses a gerund ("Streaming"), which conflicts with the repo's Markdown style guidance to avoid gerunds in headings. Consider reverting to the previous non-gerund heading text.

##### Streaming deserialization

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[eiriktsarpalis]

Hi @gewarren, please don't merge this yet. The initial PR is slop output that copilot created on my behalf. Let me get a few rounds of review on this first.

[BillWagner]

This LGTM as well. Let's

[eiriktsarpalis]

@gewarren I'm all done, feel free to proceed with another round of review.

[gewarren]

@BillWagner Can you reapprove?