## JsonPatch, AddNewtonsoftJson, and System.Text.Json
`AddNewtonsoftJson` replaces the `System.Text.Json` based input and output formatters used for formatting **all** JSON content. To add support for `JsonPatch` using `Newtonsoft.Json`, while leaving the other formatters unchanged, update the project's `Startup.ConfigureServices` as follows:
The preceding code requires a reference to [Microsoft.AspNetCore.Mvc.NewtonsoftJson](https://nuget.org/packages/Microsoft.AspNetCore.Mvc.NewtonsoftJson) and the following using statements:
The PUT and [PATCH](https://tools.ietf.org/html/rfc5789) methods are used to update an existing resource. The difference between them is that PUT replaces the entire resource, while PATCH specifies only the changes.
## JSON Patch
[JSON Patch](https://tools.ietf.org/html/rfc6902) is a format for specifying updates to be applied to a resource. A JSON Patch document has an array of *operations*. Each operation identifies a particular type of change, such as add an array element or replace a property value.
For example, the following JSON documents represent a resource, a JSON patch document for the resource, and the result of applying the patch operations.
* The `op` property indicates the type of operation.
* The `path` property indicates the element to update.
* The `value` property provides the new value.
### Resource after patch
Here's the resource after applying the preceding JSON Patch document:
```json
{
"customerName": "Barry",
"orders": [
{
"orderName": "Order0",
"orderType": null
},
{
"orderName": "Order1",
"orderType": null
},
{
"orderName": "Order2",
"orderType": null
}
]
}
```
The changes made by applying a JSON Patch document to a resource are atomic: if any operation in the list fails, no operation in the list is applied.
## Path syntax
The [path](https://tools.ietf.org/html/rfc6901) property of an operation object has slashes between levels. For example, `"/address/zipCode"`.
Zero-based indexes are used to specify array elements. The first element of the `addresses` array would be at `/addresses/0`. To `add` to the end of an array, use a hyphen (-) rather than an index number: `/addresses/-`.
### Operations
The following table shows supported operations as defined in the [JSON Patch specification](https://tools.ietf.org/html/rfc6902):
|Operation | Notes |
|-----------|--------------------------------|
| `add` | Add a property or array element. For existing property: set value.|
| `remove` | Remove a property or array element. |
| `replace` | Same as `remove` followed by `add` at same location. |
| `move` | Same as `remove` from source followed by `add` to destination using value from source. |
| `copy` | Same as `add` to destination using value from source. |
| `test` | Return success status code if value at `path` = provided `value`.|
The ASP.NET Core implementation of JSON Patch is provided in the [Microsoft.AspNetCore.JsonPatch](https://www.nuget.org/packages/microsoft.aspnetcore.jsonpatch/) NuGet package.
In a real app, the code would retrieve the data from a store such as a database and update the database after applying the patch.
### Model state
The preceding action method example calls an overload of `ApplyTo` that takes model state as one of its parameters. With this option, you can get error messages in responses. The following example shows the body of a 400 Bad Request response for a `test` operation:
```json
{
"Customer": [
"The current value 'John' at path 'customerName' is not equal to the test value 'Nancy'."
]
}
```
### Dynamic objects
The following action method example shows how to apply a patch to a dynamic object.
* If `path` points to an array element: copies `from` element to location of `path` element, then runs a `remove` operation on the `from` element.
* If `path` points to a property: copies value of `from` property to `path` property, then runs a `remove` operation on the `from` property.
* If `path` points to a nonexistent property:
* If the resource to patch is a static object: the request fails.
* If the resource to patch is a dynamic object: copies `from` property to location indicated by `path`, then runs a `remove` operation on the `from` property.
The following sample patch document:
* Copies the value of `Orders[0].OrderName` to `CustomerName`.
If the value at the location indicated by `path` is different from the value provided in `value`, the request fails. In that case, the whole PATCH request fails even if all other operations in the patch document would otherwise succeed.
The `test` operation is commonly used to prevent an update when there's a concurrency conflict.
The following sample patch document has no effect if the initial value of `CustomerName` is "John", because the test fails:
[View or download sample code](https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/web-api/jsonpatch/samples/2.2). ([How to download](xref:index#how-to-download-a-sample)).
To test the sample, run the app and send HTTP requests with the following settings:
The PUT and [PATCH](https://tools.ietf.org/html/rfc5789) methods are used to update an existing resource. The difference between them is that PUT replaces the entire resource, while PATCH specifies only the changes.
## JSON Patch
[JSON Patch](https://tools.ietf.org/html/rfc6902) is a format for specifying updates to be applied to a resource. A JSON Patch document has an array of *operations*. Each operation identifies a particular type of change, such as add an array element or replace a property value.
For example, the following JSON documents represent a resource, a JSON patch document for the resource, and the result of applying the patch operations.
Zero-based indexes are used to specify array elements. The first element of the `addresses` array would be at `/addresses/0`. To `add` to the end of an array, use a hyphen (-) rather than an index number: `/addresses/-`.
### Operations
The following table shows supported operations as defined in the [JSON Patch specification](https://tools.ietf.org/html/rfc6902):
|Operation | Notes |
|-----------|--------------------------------|
| `add` | Add a property or array element. For existing property: set value.|
| `remove` | Remove a property or array element. |
| `replace` | Same as `remove` followed by `add` at same location. |
| `move` | Same as `remove` from source followed by `add` to destination using value from source. |
| `copy` | Same as `add` to destination using value from source. |
| `test` | Return success status code if value at `path` = provided `value`.|
The ASP.NET Core implementation of JSON Patch is provided in the [Microsoft.AspNetCore.JsonPatch](https://www.nuget.org/packages/microsoft.aspnetcore.jsonpatch/) NuGet package. The package is included in the [Microsoft.AspnetCore.App](xref:fundamentals/metapackage-app) metapackage.
In a real app, the code would retrieve the data from a store such as a database and update the database after applying the patch.
### Model state
The preceding action method example calls an overload of `ApplyTo` that takes model state as one of its parameters. With this option, you can get error messages in responses. The following example shows the body of a 400 Bad Request response for a `test` operation:
```json
{
"Customer": [
"The current value 'John' at path 'customerName' is not equal to the test value 'Nancy'."
]
}
```
### Dynamic objects
The following action method example shows how to apply a patch to a dynamic object.
* If `path` points to an array element: copies `from` element to location of `path` element, then runs a `remove` operation on the `from` element.
* If `path` points to a property: copies value of `from` property to `path` property, then runs a `remove` operation on the `from` property.
* If `path` points to a nonexistent property:
* If the resource to patch is a static object: the request fails.
* If the resource to patch is a dynamic object: copies `from` property to location indicated by `path`, then runs a `remove` operation on the `from` property.
The following sample patch document:
* Copies the value of `Orders[0].OrderName` to `CustomerName`.
If the value at the location indicated by `path` is different from the value provided in `value`, the request fails. In that case, the whole PATCH request fails even if all other operations in the patch document would otherwise succeed.
The `test` operation is commonly used to prevent an update when there's a concurrency conflict.
The following sample patch document has no effect if the initial value of `CustomerName` is "John", because the test fails:
[View or download sample code](https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/web-api/jsonpatch/samples/2.2). ([How to download](xref:index#how-to-download-a-sample)).
