version: "1.0.0"

name: newtonsoft-json-migration description: > Migrates .NET projects from Newtonsoft.Json to System.Text.Json. Use when user wants to replace Newtonsoft.Json, switch to System.Text.Json, migrate JSON library, or modernize JSON serialization. requires-extension: upgrade-dotnet metadata: discovery: scenario importance: low traits: .NET|CSharp|VisualBasic|DotNetCore scenarioTraitsSet: ".NET"

Newtonsoft.Json to System.Text.Json Migration

Wire-Contract Gate

During assessment, identify Framework HTTP hosts and dependent libraries whose response models or serialization this change touches. Before planning replacement for those scopes, load migrating-webapi-odata and apply its compatibility gate, including non-OData responses. Require a scoped PASS, or evidence-backed NOT APPLICABLE from its applicability check for code with no affected HTTP consumers. On STOP, unknown evidence, or an unavailable gate, retain the original serializer and dependencies; do not put that scope into automatic conversion or cleanup. Add #skill:migrating-webapi-odata and the record path to affected tasks and their children. Direct invocation of this scenario follows the same prerequisite.

1. Assessment

Scan the solution to build a complete picture of Newtonsoft.Json usage. Capture findings in assessment.md.

Packages to Scan For

Search all project files and package management files (Directory.Packages.props) for:

• Newtonsoft.Json (direct package reference)
• Newtonsoft.Json.Bson, Newtonsoft.Json.Schema, or other Newtonsoft extension packages
• Third-party packages that depend on Newtonsoft.Json (these may force a dual-library situation)

File Inventory

Search all code files across the solution for using Newtonsoft.Json (and variations like using Newtonsoft.Json.Linq). Record which files in which projects contain these usings — this gives a quick per-project file count that drives planning.

Code Patterns to Identify

The patterns below help gauge complexity per project. You don't need to search for each one separately — note them as you encounter them during the usings scan or during execution:

Risk Indicators

Flag these as higher complexity in the assessment:

• Public API exposure: Methods/properties returning or accepting JObject, JToken, or Newtonsoft-attributed types — downstream breaking change
• Custom converters: JsonConverter<T> subclasses — API surface differs significantly between libraries
• Dynamic/JToken manipulation: Heavy use of JObject.Parse, LINQ-to-JSON — requires structural rewrite to JsonDocument or JsonNode
• Non-default serializer settings: Custom ContractResolver, ReferenceLoopHandling, or PreserveReferencesHandling — some have no direct System.Text.Json equivalent

Assessment Output

Create assessment.md in the workflow folder with this structure:

# Assessment: Newtonsoft.Json to System.Text.Json

## Affected Projects
| Project | Newtonsoft Packages | Key Patterns | Public API Exposure | Risk |
|---------|---------------------|-------------|---------------------|------|
| MyApp.Core | Newtonsoft.Json | JObject manipulation, custom converters | Yes — API returns JObject | High |
| MyApp.Web | Newtonsoft.Json | JsonConvert, [JsonProperty] | No | Low |

## Transitive Consumers
Projects that reference affected projects but don't directly use Newtonsoft:
-[list or "none"]

## Key Findings
-[Notable patterns, risks, or decisions needed]

2. Planning

Based on the assessment, create plan.md with tasks ordered bottom-up (leaf dependencies first, then consumers).

For each task include:

• Which projects or groups of projects are covered
• What changes are needed (packages, code patterns)
• Risk level and anything requiring user decision

Projects exposing Newtonsoft types in public APIs should be migrated before their consumers. Projects that are transitive-only consumers still need a task if their code references types that will change.

3. Execution

Execute the plan task by task. For any task that involves migrating Newtonsoft.Json code or packages, apply the migrating-newtonsoft-to-system-text-json feature skill. It provides API mappings, package changes, code transformations, and validation steps.

After completing approved tasks, search for remaining Newtonsoft.Json references. Fix stragglers only within approved scope; report retained references in STOP scopes without changing them or their shared central package versions.

4. Validation

• Build the full solution — zero errors required
• No remaining Newtonsoft.Json references in approved scope; protected scopes retain theirs
• If the project had tests, run them and report results