The JSON library System.Text.Json now supports the JSON Patch standard according to RFC 6902. JSON Patch is a standardized format for expressing changes to JSON documents in the form of a sequence of operations. Each operation specifies the type of change (add, remove, replace, move, copy or test) as well as the path within the JSON document to which the modification refers.
The Dotnet Doctor – Holger Schwichtenberg
Dr. Holger Schwichtenberg is the technical director of the expert network www.IT-Visions.de, which, with 53 renowned experts, supports numerous medium-sized and large companies with consulting and training as well as with software development. Through his appearances at numerous national and international conferences as well as more than 90 specialist books and more than 1,500 specialist articles, Holger Schwichtenberg is one of the best-known experts for .NET and web technologies in Germany.
This structured description allows incremental changes to be transferred efficiently without having to replace the entire document again. Especially in RESTful web APIs, JSON Patch is an established means of implementing partial updates via HTTP-PATCH.
Heise conference: betterCode() .NET 11.0
This is new in .NET 11.0: Dr. Holger Schwichtenberg and other experts will present the changes for developers at the betterCode() .NET 11.0 online conference on November 17, 2026. Early bird tickets are available in the online shop.
A key feature of JSON Patch is the strict definition of the path information via JSON Pointer (RFC 6901), see example in the following table. This means that changes are addressed clearly and precisely. JSON Patch is also suitable for complex data models with deep nesting or arrays.
Operation Description Fields Example add Adds a value to a specified path. path, value { "op": "add", "path": "/a/b/c", "value": "foo" } remove Removes the value at a specific path. path { "op": "remove", "path": "/a/b/c" } replace Replaces the value on a path with a new one. path, value { "op": "replace", "path": "/a/b/c", "value": 42 } move Moves a value from one path to another. from, path { "op": "move", "from": "/a/b/c", "path": "/a/b/d" } copy Copies a value from one path to another. from, path { "op": "copy", "from": "/a/b/c", "path": "/a/b/e" } test Tests whether a value on a path corresponds to a specific value. path, value { "op": "test", "path": "/a/b/c", "value": "foo" }
The advantage of JSON Patch is particularly evident with large objects and limited bandwidth, as only incremental changes are transmitted. For very small data structures, the overhead of creating and processing a patch document can be greater than the gain over a full update.
Previously, you had to use the older community library Newtonsoft.Json for JSON Patch. Now it also works with the newer Microsoft library System.Text.Json.
For JSON Patch with System.Text.Json, there is an extension for System.Text.Json in the form of the new NuGet package Microsoft.AspNetCore.JsonPatch.SystemTextJson, which was first released together with .NET 10.0 Preview 4.
Despite the “AspNetCore” in the name, this additional package also works outside of ASP.NET Core.
Microsoft promises "improved performance and reduced memory usage compared to the existing implementation in Newtonsoft.Json" in the new implementation, along with a similar design to Newtonsoft.Json, including updates to embedded objects and arrays. JSON patch for dynamic objects is not yet available because Newtonsoft.Json uses reflection for it. System.Text.Json should also work with the NativeAOT compiler.
Unfortunately, the new JSON patch package does not work in conjunction with modern .NET's NativeAOT compiler, only with the Just-in-Time compiler.
In the NuGet package Microsoft.AspNetCore.JsonPatch.SystemTextJson, there is a class Microsoft.AspNetCore.JsonPatch.SystemTextJson.JsonPatchDocument<T> with a method ApplyTo(obj) that applies a JSON patch operation to the passed object. Before applying ApplyTo(), load the JSON patch document into an instance of JsonPatchDocument<T> via JsonSerializer.Deserialize<JsonPatchDocument<Person>>().
ApplyTo() expects a method in the second parameter of type Action<JsonPatchError> that accepts objects of type JsonPatchError as parameters. ApplyTo() signals incorrect operation names, incorrect paths and failed test operations as JsonPatchError. If an error occurs in one or more operations, the remaining error-free operations are still processed.
The following code shows an example of an object hierarchy:
public class Person { public string FirstName { get; set; } public string LastName { get; set; } public string PrivateWebsite { get; set; } public string CompanyWebsite { get; set; } public string PrivateEmail { get; set; } public string OfficeEmail { get; set; } public List<PhoneNumber> PhoneNumbers { get; set; } = new(); public Address Address { get; set; } } public class Address { public string Street { get; set; } public string City { get; set; } public string State { get; set; } public string ZipCode { get; set; } } public enum PhoneNumberType { Mobile, Home, Work, Other } public class PhoneNumber { public string? Number { get; set; } public PhoneNumberType Type { get; set; } }
The following code snippet changes the object hierarchy with JSON Patch:
public void JSONPatchDemo() { CUI.Demo(); var person = new Person { FirstName = "Holger", LastName = "Schwichtenberg", PrivateEmail = "[email protected]", PrivateWebsite = "www.dotnet-doktor.de", CompanyWebsite = "www.IT-Visions.de", PhoneNumbers = [new PhoneNumber() { Number = "0201 649590-0", Type = PhoneNumberType.Work }], Address = new Address { Street = "Fahrenberg 40b", City = "Essen", State = "NRW" } }; CUI.H2("Output the object in its old state"); CUI.Print(ITVisions.ObjectDumper.Dump(person)); string jsonPatch = """ [ { "op": "test", "path": "/FirstName", "value": "Holger" }, { "op": "test", "path": "/LastName", "value": "Schwichtenberg" }, { "op": "replace", "path": "/FirstName", "value": "Dr. Holger" }, { "op": "move", "from": "/PrivateEmail", "path": "/OfficeEmail" }, { "op": "remove", "path": "/PrivateWebsite" }, { "op": "add", "path": "/Address/ZipCode", "value": "45257" }, { "op": "add", "path": "/PhoneNumbers/-", "value": { "Number": "0201 649590-40" } } ] """; JsonPatchDocument<Person> patchDoc = JsonSerializer.Deserialize<JsonPatchDocument<Person>>(jsonPatch); patchDoc!.ApplyTo(person, patchError => CUI.PrintError(patchError.ErrorMessage)); CUI.H2("Output the object in its new state"); CUI.Print(ITVisions.ObjectDumper.Dump(person)); }
Alternatively, you can also output the object as JSON. I deliberately left this out in the listing above so that it doesn't give the impression that you have to continue using the object as JSON. The following code shows the output as JSON:
var serializerOptions = new JsonSerializerOptions() { IndentSize = 1, WriteIndented=true, IncludeFields = true, }; Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));
