Improve deserialization of JSON primitives into JsonElement

[PranavSenthilnathan]

When creating JsonElement there is an extra overhead of creating and storing the MetadataDb in addition to the required UTF-8 payload. We can reduce this overhead by caching readonly databases for primitives of small length. This PR only affects deserialization of JsonElement when it is part of a larger deserialization, like extension data and dictionaries (if the value is object, JsonElement, or JsonNode). This should cover most places where a JsonElement of a primitive is created, but there's nothing preventing us from extending it to top level JsonElement deserialization as well.

Caching is based on the length in bytes of the UTF-8 JSON payload. The threshold was arbitrarily chosen - numbers have threshold of 8 bytes and strings 16 bytes.

The perf results show up to ~20% improvement in some cases.

Benchmarks

BenchmarkDotNet v0.14.1-nightly.20250107.205, Windows 11 (10.0.26100.4061)
AMD Ryzen 9 9950X 4.30GHz, 1 CPU, 32 logical and 16 physical cores
.NET SDK 10.0.100-preview.3.25201.16
  [Host]     : .NET 10.0.0 (10.0.25.17105), X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI
  Job-TYDCSN : .NET 10.0.0 (42.42.42.42424), X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI
  Job-ODTNID : .NET 10.0.0 (42.42.42.42424), X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI

PowerPlanMode=00000000-0000-0000-0000-000000000000  IterationTime=250ms  MaxIterationCount=20  
MinIterationCount=15  WarmupCount=1  

Method	Toolchain	Payload	Mean	Ratio	Allocated	Alloc Ratio
Baseline	main	{ "Foo": "foo", "Bar": "barValue" }	163.0 ns	1.00	264 B	1.00
Baseline	PR	{ "Foo": "foo", "Bar": "barValue" }	163.2 ns	1.00	264 B	1.00
DeserializeObjectDictionary	main	{ "Foo": "foo", "Bar": "barValue" }	197.3 ns	1.00	656 B	1.00
DeserializeObjectDictionary	PR	{ "Foo": "foo", "Bar": "barValue" }	175.7 ns	0.89	560 B	0.85
DeserializeJsonNodeDictionary	main	{ "Foo": "foo", "Bar": "barValue" }	152.1 ns	1.00	464 B	1.00
DeserializeJsonNodeDictionary	PR	{ "Foo": "foo", "Bar": "barValue" }	149.7 ns	0.98	464 B	1.00
DeserializeJsonElementDictionary	main	{ "Foo": "foo", "Bar": "barValue" }	189.2 ns	1.00	616 B	1.00
DeserializeJsonElementDictionary	PR	{ "Foo": "foo", "Bar": "barValue" }	156.0 ns	0.82	520 B	0.84
DeserializeExtensionObjectDictionary	main	{ "Foo": "foo", "Bar": "barValue" }	211.8 ns	1.00	680 B	1.00
DeserializeExtensionObjectDictionary	PR	{ "Foo": "foo", "Bar": "barValue" }	175.7 ns	0.83	584 B	0.86
DeserializeExtensionJsonElementDictionary	main	{ "Foo": "foo", "Bar": "barValue" }	206.0 ns	1.00	640 B	1.00
DeserializeExtensionJsonElementDictionary	PR	{ "Foo": "foo", "Bar": "barValue" }	178.1 ns	0.86	544 B	0.85
DeserializeExtensionJsonObject	main	{ "Foo": "foo", "Bar": "barValue" }	173.3 ns	1.00	544 B	1.00
DeserializeExtensionJsonObject	PR	{ "Foo": "foo", "Bar": "barValue" }	176.9 ns	1.02	544 B	1.00
Baseline	main	{ "Foo": 42, "Bar": 3.14 }	176.1 ns	1.00	256 B	1.00
Baseline	PR	{ "Foo": 42, "Bar": 3.14 }	172.6 ns	0.98	256 B	1.00
DeserializeObjectDictionary	main	{ "Foo": 42, "Bar": 3.14 }	208.5 ns	1.00	632 B	1.00
DeserializeObjectDictionary	PR	{ "Foo": 42, "Bar": 3.14 }	165.3 ns	0.79	552 B	0.87
DeserializeJsonNodeDictionary	main	{ "Foo": 42, "Bar": 3.14 }	212.2 ns	1.00	664 B	1.00
DeserializeJsonNodeDictionary	PR	{ "Foo": 42, "Bar": 3.14 }	171.7 ns	0.81	584 B	0.88
DeserializeJsonElementDictionary	main	{ "Foo": 42, "Bar": 3.14 }	207.8 ns	1.00	592 B	1.00
DeserializeJsonElementDictionary	PR	{ "Foo": 42, "Bar": 3.14 }	162.1 ns	0.78	512 B	0.86
DeserializeExtensionObjectDictionary	main	{ "Foo": 42, "Bar": 3.14 }	215.9 ns	1.00	656 B	1.00
DeserializeExtensionObjectDictionary	PR	{ "Foo": 42, "Bar": 3.14 }	189.3 ns	0.88	576 B	0.88
DeserializeExtensionJsonElementDictionary	main	{ "Foo": 42, "Bar": 3.14 }	214.4 ns	1.00	616 B	1.00
DeserializeExtensionJsonElementDictionary	PR	{ "Foo": 42, "Bar": 3.14 }	175.4 ns	0.82	536 B	0.87
DeserializeExtensionJsonObject	main	{ "Foo": 42, "Bar": 3.14 }	235.0 ns	1.00	744 B	1.00
DeserializeExtensionJsonObject	PR	{ "Foo": 42, "Bar": 3.14 }	200.0 ns	0.85	664 B	0.89

Benchmarking code

[HideColumns("Job", "Min", "Max", "Median", "Error", "StdDev", "RatioSD", "Gen0")]
public class ExtensionJson
{
    private const string JsonStringValues = "{ \"Foo\": \"foo\", \"Bar\": \"barValue\" }";
    private const string JsonNumberValues = "{ \"Foo\": 42, \"Bar\": 3.14 }";

    [Params(JsonStringValues, JsonNumberValues)]
    public string Payload { get; set; }

    [Benchmark]
    [BenchmarkCategory(Categories.Libraries, Categories.JSON)]
    public object Baseline() =>
        JsonSerializer.Deserialize<JsonElement>(Payload)!;

    [Benchmark]
    [BenchmarkCategory(Categories.Libraries, Categories.JSON)]
    public object DeserializeObjectDictionary() =>
        JsonSerializer.Deserialize<Dictionary<string, object>>(Payload)!;

    [Benchmark]
    [BenchmarkCategory(Categories.Libraries, Categories.JSON)]
    public object DeserializeJsonNodeDictionary() =>
        JsonSerializer.Deserialize<Dictionary<string, JsonNode>>(Payload)!;

    [Benchmark]
    [BenchmarkCategory(Categories.Libraries, Categories.JSON)]
    public object DeserializeJsonElementDictionary() =>
        JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(Payload)!;

    [Benchmark]
    [BenchmarkCategory(Categories.Libraries, Categories.JSON)]
    public object DeserializeExtensionObjectDictionary() =>
        JsonSerializer.Deserialize<ExtensionObjectDictionary>(Payload)!;

    [Benchmark]
    [BenchmarkCategory(Categories.Libraries, Categories.JSON)]
    public object DeserializeExtensionJsonElementDictionary() =>
        JsonSerializer.Deserialize<ExtensionJsonElementDictionary>(Payload)!;

    [Benchmark]
    [BenchmarkCategory(Categories.Libraries, Categories.JSON)]
    public object DeserializeExtensionJsonObject() =>
        JsonSerializer.Deserialize<ExtensionJsonObject>(Payload)!;

    public class ExtensionObjectDictionary
    {
        [JsonExtensionData]
        public Dictionary<string, object> Properties { get; set; }
    }

    public class ExtensionJsonElementDictionary
    {
        [JsonExtensionData]
        public Dictionary<string, JsonElement> Properties { get; set; }
    }

    public class ExtensionJsonObject
    {
        [JsonExtensionData]
        public JsonObject Properties { get; set; }
    }
}

[Copilot]

Pull Request Overview

This PR improves deserialization of JSON primitives into JsonElement by caching immutable MetadataDb instances for common literal values, strings, and numbers. Key changes include updating Parse methods to use a ref Utf8JsonReader and introducing token-specific caching in MetadataDb, along with a minor adjustment in the metadata buffer sizing logic.

• Updated Parse logic to pass reader by reference and select caching based on token type.
• Introduced new MetadataDb creation methods (for literal, string, and number values) and a locked cache for small primitives.
• Adjusted the condition for enlarging the MetadataDb buffer.

Reviewed Changes

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

File	Description
JsonDocument.Parse.cs	Adjusted parsing logic to use ref Utf8JsonReader and to call new CreateLockedFor* methods based on token type.
JsonDocument.MetadataDb.cs	Introduced new caching methods for literals, strings, and numbers, and modified the buffer enlargement check.

Comments suppressed due to low confidence (2)

src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.MetadataDb.cs:266

• Changing the condition from '>=' to '>' alters when the buffer is enlarged. Please verify that the new check correctly prevents buffer overflows when appending new rows.

if (Length > _data.Length - DbRow.Size)

src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.Parse.cs:771

• Subtracting 2 from the payload length assumes that the JSON string always includes both starting and ending quotes. Please confirm that this logic safely handles all edge cases.

MetadataDb database = MetadataDb.CreateLockedForString(utf8Json.Length - 2, reader.ValueIsEscaped);

[dotnet-policy-service]

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

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.