[API Proposal]: Add System.Text.Json built-in support for more numeric types

[eiriktsarpalis]

Background and motivation

System.Text.Json does not currently have built-in support for Int128/UInt128 and Half.

API Proposal

namespace System.Text.Json.Serialization.Metadata;

public partial class JsonMetadataServices
{
    public static JsonConverter<Int128> Int128Converter { get; }
    public static JsonConverter<UInt128> UInt128Converter { get; }
    public static JsonConverter<Half> HalfConverter { get; }
}

API Usage

The JsonMetadataServices APIs are marked EditorBrowsable.Never and are only intended for use by the source generator.

Alternative Designs

Note that this proposes adding numeric type support on the converter level only and not on the Utf8JsonWriter/Utf8JsonReader types or the DOM types. Since the underlying types do not have support for large numbers representable in Int128 or BigInteger, we need to make use of other primitives. Examples of this can be found in this PR. Deserialization without incurring allocation also necessitates making this change.

Risks

Adding built-in support for new types risks regressing code size for apps that use both reflection and trimming such as Blazor. If folks think this is unacceptable, we might consider making these opt-in specifically for reflection, requiring users to manually touch the relevant converters:

var options = new JsonSerializerOptions {  Converters = { JsonMetadataServices.BigIntegerConverter } };

Although it goes without saying this would introduce inconsistent behavior between the two serializers.

Related to #86442

[ghost]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

System.Text.Json does not currently have built-in support for Int128/UInt128, Half and BigInteger.

API Proposal

namespace System.Text.Json.Serialization.Metadata;

public partial class JsonMetadataServices
{
    public static JsonConverter<Int128> Int128Converter { get; }
    public static JsonConverter<UInt128> UInt128Converter { get; }
    public static JsonConverter<Half> HalfConverter { get; }
    public static JsonConverter<BigInteger> BigIntegerConverter { get; }
}

API Usage

The JsonMetadataServices APIs are marked EditorBrowsable.Never and are only intended for use by the source generator.

Alternative Designs

No response

Risks

Adding built-in support for new types risks regressing code size for apps that use both reflection and trimming such as Blazor. If folks think this is unacceptable, we might consider making these opt-in specifically for reflection, requiring users to manually touch the relevant converters:

var options = new JsonSerializerOptions {  Converters = { JsonMetadataServices.BigIntegerConverter } };

Although it goes without saying this would introduce inconsistent behavior between the two serializers.

Author:	eiriktsarpalis
Assignees:	eiriktsarpalis
Labels:	api-suggestion, area-System.Text.Json, untriaged
Milestone:	-

[ghost]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

System.Text.Json does not currently have built-in support for Int128/UInt128, Half and BigInteger.

API Proposal

namespace System.Text.Json.Serialization.Metadata;

public partial class JsonMetadataServices
{
    public static JsonConverter<Int128> Int128Converter { get; }
    public static JsonConverter<UInt128> UInt128Converter { get; }
    public static JsonConverter<Half> HalfConverter { get; }
    public static JsonConverter<BigInteger> BigIntegerConverter { get; }
}

API Usage

The JsonMetadataServices APIs are marked EditorBrowsable.Never and are only intended for use by the source generator.

Alternative Designs

No response

Risks

Adding built-in support for new types risks regressing code size for apps that use both reflection and trimming such as Blazor. If folks think this is unacceptable, we might consider making these opt-in specifically for reflection, requiring users to manually touch the relevant converters:

var options = new JsonSerializerOptions {  Converters = { JsonMetadataServices.BigIntegerConverter } };

Although it goes without saying this would introduce inconsistent behavior between the two serializers.

Author:	eiriktsarpalis
Assignees:	eiriktsarpalis
Labels:	area-System.Text.Json, blocking, api-ready-for-review
Milestone:	8.0.0

[Sergio0694]

More of a side question, but out of curiosity:

"The JsonMetadataServices APIs are marked EditorBrowsable.Never and are only intended for use by the source generator."

Why is that the case? I get that they're more advanced and specific APIs (in fact they're in a different namespace too), but why make them entirely not visible? I've found myself using them in a few cases, namely when writing custom converters. It's pretty handy to be able to get some specific built-in converters in those cases and then build your own custom converter on top of them, using composition. Would it make sense to consider making that type not hidden? 🤔

[eiriktsarpalis]

The short answer is that these served as proxy APIs back when contract customization wasn't available. The plan is to eventually have the source generator retarget contract customization APIs only and obsolete JsonMetadataServices (although it's a missing a few pieces before that becomes possible).

[eiriktsarpalis]

Punting BigInteger from the proposal since we'd probably need to implement a max digit cutoff in the API surface as well.

[bartonjs]

Video

Looks good as proposed. There was discussion to inspire a future change of accepting things based on the new numeric interfaces, but that's not for this issue. There was also a question of whether nint/nuint should be included, and the answer was 'no'.

namespace System.Text.Json.Serialization.Metadata;

public partial class JsonMetadataServices
{
    public static JsonConverter<Int128> Int128Converter { get; }
    public static JsonConverter<UInt128> UInt128Converter { get; }
    public static JsonConverter<Half> HalfConverter { get; }
}