System.Text.Json — (de)serialize JSON from .NET
System.Text.Json (STJ) ships in the .NET shared framework — on modern .NET you need no package
reference. Three namespaces matter: JsonSerializer, JsonSerializerOptions, JsonDocument and
Utf8JsonReader/Utf8JsonWriter live in System.Text.Json; [JsonPropertyName], [JsonIgnore],
[JsonConverter] and JsonSerializerContext live in System.Text.Json.Serialization; the mutable
DOM types JsonNode/JsonObject/JsonArray live in System.Text.Json.Nodes.
Use the System.Text.Json skills, not the web. Do NOT web_search / web_fetch for STJ usage —
they are authoritative and version-matched. STJ is NOT Newtonsoft.Json: web snippets frequently mix
the two APIs (JsonConvert, JsonProperty, JObject) which do not exist here. This skill covers
the core pattern; Newtonsoft migration, source generation / Native AOT, custom converters and
polymorphism, DOM / streaming, and .NET 10+ strictness are covered separately.
The core pattern
using System.Text.Json;
var options = new JsonSerializerOptions
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase, // PascalCase members -> camelCase JSON
PropertyNameCaseInsensitive = true, // read camelCase/PascalCase either way
DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull,
WriteIndented = true,
};
string json = JsonSerializer.Serialize(value, options);
var back = JsonSerializer.Deserialize<MyType>(json, options);
JsonSerializerOptions is STJ's JsonSerializerSettings. Build it once and reuse it — a fresh
options instance is expensive (it caches per-type metadata on first use). A cached static readonly
instance is the norm; options become effectively read-only after first (de)serialization.
JsonSerializerDefaults.Web (new JsonSerializerOptions(JsonSerializerDefaults.Web)) is a shortcut
for the common web shape: camelCase naming and case-insensitive reads in one.
Gotchas (compile-clean but wrong)
- Case sensitivity — the silent break. STJ matches property names case-sensitively by default
(Newtonsoft is case-insensitive). camelCase JSON into PascalCase members yields null/0/default,
no exception. Fix with
PropertyNameCaseInsensitive = true, JsonSerializerDefaults.Web,
PropertyNamingPolicy = JsonNamingPolicy.CamelCase, or [JsonPropertyName("...")] per member.
- Public fields are ignored by default (Newtonsoft includes them). Opt in with
IncludeFields = true or [JsonInclude] on the field.
- Non-public getters/setters are ignored. Use
[JsonInclude] or make the accessor public.
- Comments and trailing commas throw by default. Opt in with
ReadCommentHandling = JsonCommentHandling.Skip and AllowTrailingCommas = true.
- Enums serialize as numbers by default. For string enums use
JsonStringEnumConverter
(converters are covered separately).
- Object cycles throw at runtime. A graph that points back at itself (a parent/child pair, a
Next that reaches the root again) compiles cleanly and then fails with
JsonException: A possible object cycle was detected. The message goes on to blame "object depth
is larger than the maximum allowed depth of 64", so it reads like a depth limit to raise rather
than a cycle to handle. Set ReferenceHandler = ReferenceHandler.IgnoreCycles to write null at
the point of repetition ({"Name":"root","Next":null}), or ReferenceHandler.Preserve to emit
$id/$ref metadata ({"$id":"1","Name":"root","Next":{"$ref":"1"}}), which preserves the shape
well enough to round-trip. Both live in System.Text.Json.Serialization.
required members and non-nullable reference types are not enforced on deserialize unless you
opt in ([JsonRequired], or .NET 9+ RespectNullableAnnotations/RespectRequiredConstructorParameters).
1---2name: system-text-json3description: "Use when a .NET program (de)serializes JSON with System.Text.Json — reading/writing DTOs, configuring JsonSerializerOptions, migrating from Newtonsoft.Json, or hitting a compile-clean behavioral difference. The #1 trap: STJ matches property names CASE-SENSITIVELY by default, so camelCase JSON into PascalCase members silently yields null/default with no exception. Covers the core shapes: options, the naming/casing defaults, and the compile-clean behavioral traps. Newtonsoft migration, source generation / Native AOT, custom converters and polymorphism, DOM / streaming, and .NET 10+ strictness are covered separately. Don't web-search STJ usage — the idioms are in the System.Text.Json skills."4---56# System.Text.Json — (de)serialize JSON from .NET78`System.Text.Json` (STJ) ships in the .NET shared framework — on modern .NET you need **no package9reference**. Three namespaces matter: `JsonSerializer`, `JsonSerializerOptions`, `JsonDocument` and10`Utf8JsonReader`/`Utf8JsonWriter` live in `System.Text.Json`; `[JsonPropertyName]`, `[JsonIgnore]`,11`[JsonConverter]` and `JsonSerializerContext` live in `System.Text.Json.Serialization`; the mutable12DOM types `JsonNode`/`JsonObject`/`JsonArray` live in `System.Text.Json.Nodes`.1314> **Use the System.Text.Json skills, not the web.** Do NOT `web_search` / `web_fetch` for STJ usage —15> they are authoritative and version-matched. STJ is NOT Newtonsoft.Json: web snippets frequently mix16> the two APIs (`JsonConvert`, `JsonProperty`, `JObject`) which do not exist here. This skill covers17> the core pattern; Newtonsoft migration, source generation / Native AOT, custom converters and18> polymorphism, DOM / streaming, and .NET 10+ strictness are covered separately.1920## The core pattern2122```csharp23using System.Text.Json;2425var options = new JsonSerializerOptions26{27 PropertyNamingPolicy = JsonNamingPolicy.CamelCase, // PascalCase members -> camelCase JSON28 PropertyNameCaseInsensitive = true, // read camelCase/PascalCase either way29 DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull,30 WriteIndented = true,31};3233string json = JsonSerializer.Serialize(value, options);34var back = JsonSerializer.Deserialize<MyType>(json, options);35```3637- `JsonSerializerOptions` is STJ's `JsonSerializerSettings`. **Build it once and reuse it** — a fresh38 options instance is expensive (it caches per-type metadata on first use). A cached `static readonly`39 instance is the norm; options become effectively read-only after first (de)serialization.40- `JsonSerializerDefaults.Web` (`new JsonSerializerOptions(JsonSerializerDefaults.Web)`) is a shortcut41 for the common web shape: camelCase naming **and** case-insensitive reads in one.4243## Gotchas (compile-clean but wrong)4445- **Case sensitivity — the silent break.** STJ matches property names **case-sensitively by default**46 (Newtonsoft is case-insensitive). camelCase JSON into PascalCase members yields **null/0/default,47 no exception**. Fix with `PropertyNameCaseInsensitive = true`, `JsonSerializerDefaults.Web`,48 `PropertyNamingPolicy = JsonNamingPolicy.CamelCase`, or `[JsonPropertyName("...")]` per member.49- **Public fields are ignored by default** (Newtonsoft includes them). Opt in with50 `IncludeFields = true` or `[JsonInclude]` on the field.51- **Non-public getters/setters are ignored.** Use `[JsonInclude]` or make the accessor public.52- **Comments and trailing commas throw by default.** Opt in with53 `ReadCommentHandling = JsonCommentHandling.Skip` and `AllowTrailingCommas = true`.54- **Enums serialize as numbers by default.** For string enums use `JsonStringEnumConverter`55 (converters are covered separately).56- **Object cycles throw at runtime.** A graph that points back at itself (a parent/child pair, a57 `Next` that reaches the root again) compiles cleanly and then fails with58 `JsonException: A possible object cycle was detected.` The message goes on to blame "object depth59 is larger than the maximum allowed depth of 64", so it reads like a depth limit to raise rather60 than a cycle to handle. Set `ReferenceHandler = ReferenceHandler.IgnoreCycles` to write `null` at61 the point of repetition (`{"Name":"root","Next":null}`), or `ReferenceHandler.Preserve` to emit62 `$id`/`$ref` metadata (`{"$id":"1","Name":"root","Next":{"$ref":"1"}}`), which preserves the shape63 well enough to round-trip. Both live in `System.Text.Json.Serialization`.64- **`required` members and non-nullable reference types** are not enforced on deserialize unless you65 opt in (`[JsonRequired]`, or .NET 9+ `RespectNullableAnnotations`/`RespectRequiredConstructorParameters`).