Nerdbank.Json

Nerdbank.Json is a UTF-8 JSON serializer being built in the same general shape as Nerdbank.MessagePack, but without layering on top of System.Text.Json, Newtonsoft.Json, or any other serializer.

The implementation includes low-level UTF-8 readers and writers, built-in converters for common .NET types, and PolyType-backed serialization for mutable and constructor-bound object graphs. It supports incremental asynchronous streaming, reference preservation, unions, targeted deserialization, and JSON Schema generation. It is allocation-conscious in the hot path and multi-targets net10.0, net472, and netstandard2.0.

Features

• Direct UTF-8 JSON writing to IBufferWriter<byte>.
• Direct writer-buffer reservations for complete trusted JSON values through GetSpan / Advance, plus overloaded stateless boolean and numeric primitives for all integer widths, single/double precision, and decimal.
• Borrowed segmented UTF-8 parsing, decoded UTF-8 string views, token inspection, and stateless scalar primitives.
• Caller-owned scratch for split numeric/property tokens and incremental string decoding, with pooled fallbacks for large tokens rather than fixed token-size limits.
• RawJson values with explicit borrowed/owned lifetimes and automatic owned deserialization.
• RFC 8259 string escaping, limited to the characters that must be escaped.
• Built-in serialization and deserialization for common .NET primitive and BCL types.
• PolyType-driven serialization for mutable objects, records, and immutable objects with mapped constructor parameters.
• Mutable and parameterized collections and dictionaries, including read-only and immutable types when their PolyType shapes supply construction support.
• Dictionaries with supported simple scalar or enum keys, getter-only mutable collection population, and rectangular multidimensional arrays with nested or flat representations.
• camelCase property naming by default, configurable with JsonNamingPolicy.
• Optional indented output for human-readable JSON.
• Optional case-insensitive property-name matching during deserialization.
• Optional enum-name serialization with numeric fallback for unnamed values.
• Runtime custom converter registration with immutable converter instance/type collections or converter factories using ConverterContext.
• Attribute-driven custom converter registration on types, properties, and constructor parameters, with automatic generated constructor associations for ordinary and open-generic converters.
• Optional unknown-member retention through a member of type UnusedDataPacket.
• Built-in byte buffer handling using Base64 JSON strings.
• Optional trailing-comma and comment skipping support during deserialization.
• Configurable deserialization policy for missing required values and non-nullable reference validation.
• Optional reference preservation for repeated references, with either cycle rejection or support for cycles through mutable objects and collections.
• Synchronous stream APIs and incremental asynchronous stream/pipe serialization with cancellation and backpressure.
• Asynchronous sequence reading and writing through DeserializeEnumerableAsync and SerializeEnumerableAsync, with SequenceOptions selecting JsonSequenceFormat.NDJson or JsonSequenceFormat.JsonArray.
• Targeted DeserializePath by JSON path or member-access options, and DeserializePathEnumerableAsync for arrays selected inside an envelope.
• Shape-declared unions and runtime DerivedTypeUnions mappings, with array or $type metadata envelopes.
• JSON Schema draft 4, draft 7, and draft 2020-12 export as System.Text.Json.Nodes.JsonObject, separate from the native JSON DOM.
• Serialization callbacks, operation-scoped string interning, collection comparers, and configurable security limits.
• Opt-in native JSON DOM, untyped object, ExpandoObject, and System.Text.Json DOM converters.
• A separate ASP.NET Core MVC formatter package using explicitly supplied type shapes.
• A self-checking F# sample covering records, options, and discriminated unions.
• Multi-targeting across modern .NET and .NET Framework.
• Test-driven development with focused round-trip coverage for the current built-in type surface.

Supported Built-In Types

The current built-in serializer supports:

• string, char, bool
• Numeric primitives: byte, sbyte, short, ushort, int, uint, long, ulong, float, double, decimal
• System.Numerics.BigInteger
• DateTime, DateTimeOffset, TimeSpan
• Guid, Version, Uri, CultureInfo, Encoding
• byte[], Memory<byte>, ReadOnlyMemory<byte>
• RawJson for exact UTF-8 token retention
• System.Drawing.Color, System.Drawing.Point
• On .NET 10 and later: Half, Int128, UInt128, DateOnly, TimeOnly, Rune

Example

using Nerdbank.Json;

JsonSerializer serializer = new();

string json = serializer.Serialize(new DateTimeOffset(2024, 7, 1, 12, 34, 56, TimeSpan.Zero));
DateTimeOffset value = serializer.Deserialize<DateTimeOffset>(json);

For object graphs, annotate your root type with GenerateShape and use the same serializer APIs:

using Nerdbank.Json;
using PolyType;

[GenerateShape]
public partial class Person
{
	public string? Name { get; set; }
	public int Age { get; set; }
}

JsonSerializer serializer = new();
string json = serializer.Serialize(new Person { Name = "Ada", Age = 37 });
Person person = serializer.Deserialize<Person>(json);

This is the beginning of the README. Read the rest at the original. Read the full README ↗