# System Text JSON Newtonsoft Migration

> Use when migrating serialization code from Newtonsoft.Json (Json.NET) to System.Text.Json — replacing JsonConvert / JsonSerializerSettings / [JsonProperty] and reconciling the behavioral differences that compile clean but silently change output (case-sensitivity, fields, nulls, comments, dates).

- Skill: `richlander/system-text-json-newtonsoft-migration` (Agent Skill)
- Install (CLI): `npx get-skill add richlander/system-text-json-newtonsoft-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/richlander/system-text-json-newtonsoft-migration/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: richlander (https://skillmd.com/u/richlander)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/richlander/system-text-json-newtonsoft-migration

---


# Newtonsoft.Json → System.Text.Json migration

## Required setup

Remove the `Newtonsoft.Json` package reference and every `using Newtonsoft.Json;`. STJ is in the
shared framework — **no package reference is needed**. The attributes are in a different namespace
from the serializer, which is the usual post-migration compile error:

```csharp
using System.Text.Json;                 // JsonSerializer, JsonSerializerOptions
using System.Text.Json.Serialization;   // [JsonPropertyName], [JsonIgnore], [JsonConstructor], JsonIgnoreCondition
```

Then apply the API map **and** re-check the behavioral defaults, because most breaks are silent
(compile-clean, wrong output), not compiler errors. The single most common regression: STJ matches
property names **case-sensitively**, so camelCase JSON into PascalCase members yields null/default
with no exception.

> **Inventory public fields before changing calls.** Newtonsoft serializes them; STJ silently drops
> them unless `IncludeFields = true` or `[JsonInclude]` is applied. A migrated object unexpectedly
> becoming `{}` is the signature of this miss. Preserve the supplied type shape; do not convert its
> fields into properties just to make serialization work.

## API map

| Newtonsoft.Json | System.Text.Json |
| --------------- | ---------------- |
| `JsonConvert.SerializeObject(x)` | `JsonSerializer.Serialize(x)` |
| `JsonConvert.DeserializeObject<T>(s)` | `JsonSerializer.Deserialize<T>(s)` |
| `JsonSerializerSettings` | `JsonSerializerOptions` |
| `[JsonProperty("name")]` | `[JsonPropertyName("name")]` (record param: `[property: JsonPropertyName("name")]`) |
| `[JsonIgnore]` | `[JsonIgnore]` (namespace `System.Text.Json.Serialization`) |
| `[JsonConstructor]` | `[JsonConstructor]` |
| `NullValueHandling.Ignore` | `DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull` |
| `DefaultValueHandling.Ignore` | `DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault` |
| `Formatting.Indented` | `WriteIndented = true` |
| `Required.Always` on `[JsonProperty]` | `[JsonRequired]` or C# `required` |
| `ReferenceLoopHandling.Ignore` | `ReferenceHandler.IgnoreCycles` |
| `PreserveReferencesHandling.All` | `ReferenceHandler.Preserve` |
| `StringEnumConverter` | `JsonStringEnumConverter` |
| `JObject` / `JArray` / `JToken` | `JsonNode` / `JsonObject` / `JsonArray` (namespace `System.Text.Json.Nodes`) |
| `[JsonExtensionData]` | `[JsonExtensionData]` (dictionary must be `Dictionary<string, JsonElement>` or `object`) |

## Behavioral differences to reconcile (the silent ones)

- **Case-sensitivity.** Newtonsoft reads property names case-insensitively; STJ is case-sensitive by
  default → set `PropertyNameCaseInsensitive = true` (or `JsonSerializerDefaults.Web`). This is the
  single most common migration regression.
- **Fields.** Newtonsoft serializes public fields; STJ ignores them → `IncludeFields = true` /
  `[JsonInclude]`.
- **Non-public accessors.** Newtonsoft uses them; STJ ignores them → `[JsonInclude]` or make public.
- **Comments / trailing commas.** Newtonsoft allows; STJ throws → `ReadCommentHandling =
  JsonCommentHandling.Skip`, `AllowTrailingCommas = true`.
- **Dates.** No `DateFormatString`. STJ uses ISO 8601 round-trip; other formats need a custom
  `JsonConverter<DateTime>` (custom converters are covered separately). `TimeSpan` also differs.
- **Numbers.** Newtonsoft is lenient about quoted numbers; STJ rejects `"123"` into an `int` unless
  `NumberHandling = JsonNumberHandling.AllowReadingFromString`.
- **Missing vs null.** STJ leaves a member at its default when the JSON omits it (no `MissingMemberHandling`).

## Migration checklist

1. Swap package + usings + the API-map calls above.
2. Inventory public fields and preserve them with `IncludeFields` / `[JsonInclude]`.
3. Set `PropertyNameCaseInsensitive` (or `Web` defaults) if any input is camelCase.
4. Re-add comment/trailing-comma tolerance and quoted-number handling **only if the
   old code relied on them** — don't loosen defaults blindly.
5. Replace `StringEnumConverter` with `JsonStringEnumConverter`; replace date-format strings with a converter.
6. Build **and run a round-trip test** — the breaks are silent, so a compile is not enough.

