Create or update conceptual docs for new System.Text.Json features in .NET 11 #55465

Describe the issue or suggestion

Track conceptual, compatibility, and What's New documentation for user-visible System.Text.Json changes in .NET 11.

The source corpus is merged dotnet/runtime pull requests labeled area-System.Text.Json from August 10, 2025, through August 18, 2026.

Tier 1: Major documentation features

• 1. C# union serialization. Document union contracts, JsonTypeInfoKind.Union, JsonUnionAttribute, type-classifier APIs, reflection and source-generation support, and the final behavior for nullable and default-valued unions. Include JsonUnionTypeStructuralClassifier, which distinguishes cases by JSON token kind and root-level object property names. Implementation: dotnet/runtime#128162, dotnet/runtime#128900, dotnet/runtime#131797, dotnet/runtime#131879, and dotnet/runtime#132411.
• 2. JSON Lines serialization. Document the four SerializeAsyncEnumerable<T> overloads for Stream and PipeWriter. Explain that topLevelValues: true writes canonical JSONL with \n, while the default output remains a JSON array. Implementation: dotnet/runtime#127567.
• 3. F# discriminated unions. Document the string representation for fieldless cases and the $type object representation for cases with fields. State prominently that support is reflection-only and doesn't support source generation or Native AOT. Implementation: dotnet/runtime#125610.
• 4. Closed-hierarchy polymorphism inference. Document global opt-in through JsonSerializerOptions.InferClosedTypePolymorphism, source-generation configuration, and per-hierarchy configuration through JsonPolymorphicAttribute.InferClosedTypePolymorphism. Include precedence for explicit [JsonDerivedType] registrations and per-type opt-out. Implementation: dotnet/runtime#130808 and dotnet/runtime#131623.
• 5. Source generation for inaccessible members. Update the source-generation support matrix and related guidance to cover private, internal, and protected [JsonInclude] members, inaccessible [JsonConstructor] constructors, and preservation of initializer defaults for omitted init properties. Remove the existing statement that private [JsonInclude] members aren't supported. Implementation: dotnet/runtime#124650, dotnet/runtime#126507, and dotnet/runtime#130163.
• 6. Naming-policy controls. Document JsonNamingPolicy.PascalCase, JsonKnownNamingPolicy.PascalCase, and JsonNamingPolicyAttribute on types and members. Include the precedence order: JsonPropertyName → member naming-policy attribute → type naming-policy attribute → global policy → original name. Implementation: dotnet/runtime#124645 and dotnet/runtime#124644.
• 7. Type-level ignore conditions. Document [JsonIgnore(Condition = ...)] on classes, structs, and interfaces, including member-level precedence, precedence over DefaultIgnoreCondition, and the invalid Always configuration. Implementation: dotnet/runtime#124646.
• 8. Open generic derived types in polymorphism. Add examples for [JsonDerivedType(typeof(Derived<>))] on generic bases. Document supported unification patterns and the failures reported at run time or through SYSLIB1229. Implementation: dotnet/runtime#127318.
• 9. Built-in converters for new numeric types. Add BFloat16, Decimal32, Decimal64, and Decimal128 to supported-type, source-generation, and JSON Schema guidance. Include the corresponding JsonMetadataServices converter properties. Implementation: dotnet/runtime#131523.

Tier 2: Existing-topic and compatibility updates

• 10. Open generic converters on generic types. Include the new [JsonConverter(typeof(OptionConverter<>))] pattern in What's New and retain the existing conceptual guidance for direct open-generic converter use without a JsonConverterFactory. Implementation: dotnet/runtime#123209.
• 11. By-reference constructor parameters. Document deserialization support for constructors with in, ref, out, and ref readonly parameters in reflection and source-generation modes. Explain that out parameters don't bind JSON constructor arguments. Implementation: dotnet/runtime#122950.
• 12. Extension-data improvements. Update handle-overflow.md to accept IReadOnlyDictionary<string, object> and IReadOnlyDictionary<string, JsonElement>, including how deserialization materializes and preserves entries. Also account for corrected JsonObject extension-data serialization. Implementation: dotnet/runtime#120636 and dotnet/runtime#122838.
• 13. IReadOnlySet<T> support. Add IReadOnlySet<T> to supported-types.md and describe serialization as a JSON array and deserialization to a set implementation. Include JsonMetadataServices.CreateIReadOnlySetInfo. Implementation: dotnet/runtime#120306.
• 14. Generic metadata lookup. Document JsonSerializerOptions.GetTypeInfo<T>() and TryGetTypeInfo<T>(), which remove manual casts and provide a nonthrowing lookup. Implementation: dotnet/runtime#123940.
• 15. Reset writer output and options together. Document Utf8JsonWriter.Reset(Stream, JsonWriterOptions) and Reset(IBufferWriter<byte>, JsonWriterOptions) with a pooling or reuse example. Implementation: dotnet/runtime#126578.

Existing coverage and immediate gaps

The current .NET 11 libraries draft already covers or partly covers union serialization, JSON Lines, F# discriminated unions, closed-hierarchy inference, naming and ignore controls, IReadOnlySet<T>, generic metadata lookup, and writer reset overloads. converters-how-to.md already covers open generic converters.

The most important corrections and omissions are:

• source-generation-modes.md and immutability.md still state that source generation can't use private [JsonInclude] members.
• The F# discriminated-union section doesn't state its reflection-only, trimming, and Native AOT limitations.
• The naming-policy section describes JsonNamingPolicyAttribute as member-level even though it also supports types.
• The closed-hierarchy section doesn't yet cover the source-generation option, per-type attribute, opt-out behavior, or associated diagnostics.
• supported-types.md lacks IReadOnlySet<T>.
• handle-overflow.md lists only mutable dictionary extension-data types.
• extract-schema.md doesn't cover the three exporter changes.
• New numeric converters and the exception-propagation compatibility change aren't covered.

Associated WorkItem - 626184