Development documentation · Some APIs may be unreleased Published release →

Guides

JSON serialization

JsonSerializer reads and writes JSON values and maps supported objects and arrays. Use JsonValue for a document tree, or the typed overloads for nongeneric reference objects, typed arrays and root String, Int32 or Boolean values.

In-memory operations return Result with JsonError. The mapping rules and size limits below define the supported subset. Stream operations return Tasks; use await.

UTF-8 byte output (development)

JsonSerializer.SerializeToUtf8Bytes(value) and SerializeToUtf8Bytes(value, options) return Result<byte[], JsonError> containing newly owned UTF-8 storage. They accept the same supported objects and JsonValue nodes as Serialize, with the same mapping errors, 1024-byte output limit, 32-value limit and maximum container depth of four. Formatting counts toward the byte limit. Changing a returned array does not change the source node or another result.

HTTP JsonContent creation and OutputStream serialization use this byte writer. They do not construct a whole-document string or quoted-token strings. Text-returning Serialize/SerializeNode still produce owned strings because their caller requests text. Development input parsing borrows the source string’s UTF-8 bytes. Unescaped JSON strings decode directly into their final owned text; escaped strings use scratch storage. Numbers retain their original spelling, and boolean/null tokens need no temporary strings. HTTP byte input uses the borrowed overloads below; stream input still materializes whole-document text before invoking the parser. Incremental parsing and Utf8JsonReader/Utf8JsonWriter contracts remain future work.

Stream APIs validate the complete document before the first write and leave the stream open without flushing it. An output I/O failure can follow partial output; its original StreamError remains wrapped by JsonError.Write. A pending write retains its owned byte array until completion. Shared OutputStream currently accepts an array and range; the wider Memory signature migration remains separate.

UTF-8 byte input (development)

The native reference includes these synchronous overloads:

DeserializeNode(utf8: ReadOnlySlice<byte>) -> Result<JsonValue, JsonError>
Deserialize<T>(utf8: ReadOnlySlice<byte>) -> Result<T, JsonError>
Deserialize(utf8: ReadOnlySlice<byte>, type: TypeInfo) -> Result<Object, JsonError>

Only the selected window is read. Input is borrowed for the call and never stored; returned nodes, property names, strings and number lexemes own their text. Subsequent changes to the input array do not change a completed result. Mapping uses the same supported types and errors as the text overloads.

Complete strict UTF-8 validation runs without creating a document string. Malformed UTF-8 returns JsonError.Read(TextReadError.InvalidUtf8), even if a JSON syntax error appears earlier in the bytes. JSON parsing and mapping follow validation. Overlong sequences, surrogate encodings, truncated sequences and values above U+10FFFF are rejected. A BOM remains a JSON syntax/number error; it is not stripped. Empty input fails with Syntax("Missing value"); raw NUL is valid UTF-8 but invalid inside a JSON string.

String-backed readonly slices and nonzero array windows are supported. Explicit byte input does not change String's grapheme indexing or add an incremental JSON reader. The legacy CLI documentation scaffold omits these three borrowed signatures; its opaque view types cannot safely project them. This section and the native JsonSerializer member pages provide their reference.

JSON text and indentation

JsonValue.ToJsonString() returns compact JSON, including quotes and escaping for string values. Pass JsonSerializerOptions with WriteIndented = true for two-space indentation and LF newlines on every platform. Empty containers remain {} and []; no trailing newline is added.

func FormatJson(value: JsonValue) -> Result<string, JsonError> {
    let options = JsonSerializerOptions()
    options.WriteIndented = true
    return value.ToJsonString(options)
}

JsonSerializer.SerializeNode(value, options) and Serialize(value, options) use the same formatting. Their output-stream overloads also accept options and return Tasks. Options are read when serialization begins. Complete validation precedes stream writes; the stream remains open. Formatting counts toward the existing 1,024 UTF-8 byte output limit. Invalid graphs and exceeded quotas return JsonError.

Use the explicit Node methods for the DOM boundary:

DeserializeNode(text: string) -> Result<JsonValue, JsonError>
DeserializeNode(input: InputStream) -> Task<Result<JsonValue, JsonError>>
SerializeNode(value: JsonValue) -> Result<string, JsonError>
SerializeNode(output: OutputStream, value: JsonValue) -> Task<Result<unit, JsonError>>

Object mapping uses these methods:

Deserialize<T>(text: string) -> Result<T, JsonError>
Deserialize<T>(input: InputStream) -> Result<T, JsonError>
Deserialize(text: string, type: TypeInfo) -> Result<Object, JsonError>
Deserialize(input: InputStream, type: TypeInfo) -> Result<Object, JsonError>
Serialize(value: Object) -> Result<string, JsonError>
Serialize(output: OutputStream, value: Object) -> Result<unit, JsonError>

Use JsonSerializer.Deserialize<YourClass>(text)? for a typed result, or pass typeof(YourClass) to the non-generic read overload. Both use the same mapper and return the same structured errors, including UnsupportedMapping for unsupported targets such as unsupported value types and non-string map keys. Object construction requires a runtime-backed public nongeneric reference class with a public parameterless constructor. The serializer invokes real constructors/getters/setters through runtime reflection; it never writes backing fields directly. JsonValue inputs to the Object overload still use the DOM codec, including when held as Object. Prefer SerializeNode when explicitly working with nodes.

Dynamic JSON content inside typed models

Declare a property or array element as JsonValue to retain any JSON kind inside an otherwise typed model. JsonObject, JsonArray, JsonString, JsonNumber, JsonBoolean and JsonNull require the matching kind; a mismatch returns JsonError.TypeMismatch before model constructors or setters run. The same rule applies to root Deserialize<T> calls and the TypeInfo overload.

Serialization embeds node content directly. It does not reflect over node members or quote an object/array as text. Number tokens keep their spelling. JSON null is an explicit JsonNull node; CLR null references remain unsupported. Object-typed properties do not infer JSON node mapping. The complete mixed document shares the existing depth, occurrence and byte limits, including cycles inside embedded nodes.

The tested NodeEnvelope sample combines JsonValue, JsonObject and JsonValue[] properties. Supported lists and maps can also contain explicitly declared JSON nodes.

Value-record serialization (development)

Serialize also accepts public nongeneric record structs, including read-only properties and nested class/record properties. For example, a public record struct Person(val Name: string, val Age: int) holding "Bob" and 42 serializes to {"Name":"Bob","Age":42}. See the tested consumer. Native builds must retain property metadata and getters for each model type through --reflection-roots; the test driver demonstrates that configuration.

Getters execute against the boxed value. Mutating getters can change that box; the original unboxed value remains unchanged. Nested record results are copied into new boxes and traced normally. The same JSON, errors and quotas apply in interpreter, JIT and AOT. Empty records serialize as {}; fields alone are not JSON properties.

This adds serialization, not constructor mapping for record deserialization. Deserializing a non-scalar value record returns UnsupportedMapping before executing model constructors. Generic records, enum/union mapping, custom value-record array or collection elements, nonpublic model types and unsupported scalar properties remain outside the supported mapper subset. Existing bounds still apply.

Provisional property rules

  • Map String, Int32 and Boolean public instance properties, plus nested nongeneric reference objects, record structs for serialization, and typed arrays in development, with exact, case-sensitive names. No naming policy or attribute support; property order is not promised.
  • Serialize public getters, including read-only properties. Deserialize public setters; read-only/private setters and static properties are ignored. Fields are ignored.
  • Every writable mapped property must be present on input. Unknown JSON fields are ignored; duplicate decoded names remain invalid. This strict presence rule differs from .NET's default treatment of non-required missing properties.
  • Reject CLR null references, unsupported collection families, Optional, enums, unsupported scalars and indexers in participating properties. Int32 requires a checked integer token; fraction/exponent tokens are not coerced.

Development nested writes require each property value to have its declared runtime type; polymorphic properties are rejected except for explicit JsonValue declarations and the supported collection interfaces described below. Reads use each declared class and its public parameterless constructor. Shared children serialize as repeated JSON objects; deserialization constructs independent instances rather than preserving identity.

Validate the entire input tree before invoking any model constructor or setter. Setter failures and user Faults are not transactional; side effects are not rolled back. The Reflection error case retains ReflectionError. UnsupportedMapping identifies unsupported shapes through diagnostic text; ordinary syntax, missing-field, type-mismatch, number and stream causes retain their existing JsonError cases. Terminal Faults from user accessors/constructors are not wrapped.

Typed arrays

Use Deserialize<int[]>("[21,22]") or Deserialize<ReportPayload[]>(text) for root arrays. Array-valued model properties use the same mapper; strings, Int32, Boolean, supported models and jagged arrays can be elements. String/Int32/Boolean also work as root values. The non-generic TypeInfo, borrowed stream, JsonContent and generic HTTP helper paths share this behavior.

Order and empty arrays are preserved. Each array admits at most 31 elements; every object or array consumes a container level and contributes to the existing 32-value document bound. Element types are exact, with no coercion or polymorphic substitution. Null arrays/elements are rejected; missing writable array properties remain errors. Rectangular arrays and unsupported scalar elements remain outside this slice; supported collection elements use the rules below. Shared model elements serialize repeatedly and deserialize independently. The complete input tree, including later elements, is validated before any model constructor/setter runs.

Lists, sequences and string-keyed maps

Declared type JSON shape Deserialized implementation
Sequence<T>, List<T>, ArrayList<T> Array ArrayList<T>
Map<string, T>, MutableMap<string, T>, HashMap<string, T> Object HashMap<string, T>(StringComparer.Ordinal)

These exact built-in families work at roots, properties and recursively as elements. Supported element types include nested models, arrays, collections and explicit JSON nodes. Empty collections and sequence order are preserved. Map keys are case-sensitive UTF-8 strings; writing uses the map's observed key order. Reading uses ordinal comparison, so a custom comparer is not preserved by a round trip.

Object mapping retains its four-container-level and 32-value bounds even though DOM parsing now supports larger documents. Serialization retains its 1024-byte output bound. Invalid later elements fail preflight before any model constructor or setter executes. Each occurrence is constructed independently; shared references are not preserved.

Arbitrary collection implementations, custom construction factories and non-string keys are unsupported. Object element declarations still do not infer JSON nodes. Ordinary model inheritance, converters, naming policies and union mapping remain follow-up work. This is bounded development support, not general .NET serializer compatibility.

Streams and limits

Streams are borrowed, left open and not flushed. Reads consume through EOF and may consume input before failure. Writes validate mapping and the entire encoded document before touching output; a stream failure can still leave a written prefix. This is buffered synchronous conversion, not async stream parsing.

DOM reads no longer impose a fixed byte, value-count or per-container entry quota. Runtime allocation budgets still apply. Stream input is decoded in chunks and buffered in full; the text reader's existing per-grapheme 64 KiB bound remains. DOM writes still allow 1024 UTF-8 bytes (including formatting), 32 value occurrences and four container levels. Object mapping also retains its four-level/32-value bounds; reference identity and cycles are unsupported. These remaining limits are development gaps, not intended permanent JSON contracts.

Document parsing options

JsonDocumentOptions is a value type, matching the core design of System.Text.Json.JsonDocumentOptions. The text, borrowed UTF-8 and asynchronous InputStream DeserializeNode overloads accept it. Omitting options uses the same defaults:

Property Default Behavior
AllowTrailingCommas false Accept one comma before an array/object closing delimiter when true.
CommentHandling JsonCommentHandling.Disallow Skip accepts and discards line and block comments. Allow is reserved for future token readers and is rejected by document parsing, as in .NET.
MaxDepth 0 Zero means 64 nested containers. A positive value overrides this; scalar roots consume no container depth.

Options are copied for the call. Negative depth, Allow or undefined comment policies return JsonError.InvalidOptions before consuming input. This uses neoCLR's Result error model rather than .NET's throwing property setters. Exceeded depth returns LimitExceeded. Duplicate decoded property names still return DuplicateField; .NET's duplicate-property policy is not yet exposed. Generic object mapping still uses strict defaults; serializer read options are a follow-up API gap.

var options = JsonDocumentOptions()
options.CommentHandling = JsonCommentHandling.Skip
options.AllowTrailingCommas = true
let result = JsonSerializer.DeserializeNode("/* settings */{\"enabled\":true,}", options)

Comments are only recognized between tokens, never within strings or token text. Malformed/truncated comments, double commas, missing values and trailing non-comment content still fail. Neo.Configuration.Json opts into these settings, adds a 1 MiB input budget, and strips an initial UTF-8 BOM. Direct JSON parsing continues to reject a BOM. Large strings are decoded on UTF-8 scalar boundaries, including escaped strings and surrogate pairs.

HTTP content conversion

JsonContent in System.Web.Http.Json shares these operations between client requests, server requests, server responses and client responses:

Create(value: Object) -> Result<HttpContent, JsonError>
CreateNode(value: JsonValue) -> Result<HttpContent, JsonError>
Read<T>(content: HttpContent) -> Result<T, JsonError>
Read(content: HttpContent, type: TypeInfo) -> Result<Object, JsonError>
ReadNode(content: HttpContent) -> Result<JsonValue, JsonError>

Creation sets application/json; charset=utf-8. Reads interpret buffered bytes as UTF-8 JSON; the caller selects header and status policy. All operations are synchronous, preserve the serializer's errors and limits, and leave content reusable. Invalid UTF-8 is JsonError.Read(TextReadError.InvalidUtf8). Empty bytes fail JSON syntax validation; a null document is a JsonNull node, while model mapping continues rejecting it. The byte limit is checked before UTF-8 validation. Array-backed content is borrowed directly; other Sequence implementations retain one contiguous snapshot per read. No whole-document string is created. Existing sequence alias behavior is preserved between calls. Unbuffered content returns Read(IoFailure) without reading or closing its stream.

These methods do not send a request, complete/close a context or add cancellation. The mapped HTTP sample uses the same helpers on both peers. Generic HttpClient verbs are described below; automatic endpoint binding remains future work.

Error payload reference

See JSON error payloads for the case properties and their value types. Case signatures also appear on the generated JsonError union page.

Generic HTTP client helpers

Import System.Web.Http.Json.* to use HttpClientJsonExtensions. GetFromJson<T> sends GET, requires a 2xx response, and reads the model with the same buffered mapping rules as JsonContent.Read<T>. PostAsJson<T> serializes a model before sending and returns HttpResponse, preserving non-success statuses and content for the application to inspect. Both accept string or Uri addresses, with a final cancellationToken: CancellationToken = default, and honor BaseUri and DefaultRequestHeaders.

Development failures return HttpError | JsonError directly: HttpError retains HTTP/transport/status errors; JsonError retains mapping, syntax, UTF-8 and limit failures. This replaces the previous HttpJsonError return signature; rebuild consumers and use typed patterns after extracting Error. The nominal HttpJsonError remains available for explicit application contracts. Cancellation remains task cancellation. No per-call headers, serializer options, streaming codec or asynchronous serialization are introduced.

The managed report sample gets a typed report, posts it back, then reads the acknowledgement from the response. The application explicitly adapts the two client error alternatives into its AppError union; single-cause operations retain application-owned converters. The response's Request property identifies the effective POST, including client default headers.

DOM collection views

JsonObject implements Map<string, JsonValue>; JsonArray implements Sequence<JsonValue>. Object indexing uses exact field names and array indexing uses zero-based integers. Indexers return the original node, including JsonNull; a missing field or invalid index causes a terminal Fault. Use object Find/Field or array Item when absence or invalid bounds should be recoverable.

Both support ordinary for iteration. Object keys/pairs and array elements are shallow ordered snapshots: later additions do not extend an existing iterator, while child contents remain shared. Count and indexers read the current container. Mutation continues through Add; mutable collection interfaces are not implemented. Typed Serialize still recognizes nodes through these interface views.

Converter registration, serializer options and configurable property naming remain future work. Their developer experience should follow familiar .NET JSON workflows, with justified neoCLR differences rather than exact API duplication.

Asynchronous HTTP content reads

For incoming request content, use await content.ReadFromJson<T>(), await content.ReadFromJson(type) or await content.ReadJsonNode(). These handle both buffered and streaming bodies. Streaming reads consume the body once, keep content ownership with the exchange and pass the optional CancellationToken to transport reads. Strict UTF-8 and default JSON syntax/depth rules still apply; object mapping and writing retain the separate limits described above. The legacy buffered byte-sequence adapter still has a 1024-byte copy cap (a separate gap). Buffered conversion remains synchronous within the returned task.

The current stream serializer uses a bounded UTF-8 text reader before parsing, so it still materializes document text. This is not yet an incremental JSON parser or an allocation-free path. Synchronous JsonContent.Read remains a buffered-only operation and must not be used for incoming streamed requests.