Home JsonPatch.Net Basics
JsonPatch.Net Basics
Cancel

JsonPatch.Net Basics

JSON Patch is a language for modifying JSON documents. Like JSON Schema, it is also expressed in JSON.

Syntax

A patch consists of an array containing one or more operations. Each operation may also contain one or more arguments.

An operation must be one of

  • add
  • remove
  • replace
  • copy
  • move
  • test

The arguments vary among them, though all must contain at least an op and a path. (“Path” as used here is colloquial. It’s actually a JSON Pointer, not JSON Path.)

  • op specifies the operation and must be one of the values above.
  • path specifies the location within the JSON document which will receive changes.
  • from specifies a source location within the JSON document from which to pull a value.
  • value specifies an explicit value.

Applying Patches

In JsonPatch.Net, a JsonPatch object can be deserialized directly from the JSON document string.

1
var patch = JsonSerializer.Deserialize<JsonPatch>(patchString);

JsonPatch operates on JsonNode? values. To apply the patch, parse the document and pass the root element into the .Apply() method.

1
2
var doc = JsonNode.Parse(docString);
var result = patch.Apply(doc);

The result contains the altered document, either fully patched, or up to the point an error occurred along with an error message.

You can even apply a patch from one object to another! They don’t even need to be of the same type!!

1
2
var myPatchedObject = patch.Apply(myObject);
var myDifferentTypeObject = patch.Apply<MyObject, MyDifferentObject>(myObject);

Inline Patching

The JsonPatch class can also be built in code using by creating a series of PatchOperations through its static constructor methods. There’s one for each operation.

1
2
var patch = new JsonPatch(PatchOperation.Add("/foo/bar", "baz"),
                          PatchOperation.Test("/foo/biz", false));

That’s it!

Use decimal for fractional numbers in operation values and in documents that are built in code (e.g. 4.789m). On .Net 11, a node built from a double or float carries its exact binary value, so PatchOperation.Test("/foo/biz", 4.789) fails against a parsed document that contains 4.789. For the same reason, generating a patch between a parsed document and one built with double values produces replace operations for numbers that appear to be equal. Nodes parsed from JSON text are not affected. See Floating point values and .Net 11 for details.

Generating Patches

If you know what your start and end states are, but you want to find the differences, you can do that by generating a patch.

1
2
3
4
5
6
7
8
9
10
11
var start = JsonNode.Parse("[{\"test\":\"test123\"},{\"test\":\"test321\"},{\"test\":[1,2,3]},{\"test\":[1,2,4]}]");
// you can also build your data inline
var target = new JsonArray{
  new JsonObject { ["test"] = "test123" },
  new JsonObject { ["test"] = "test32132" },
  new JsonObject { ["test1"] = "test321" },
  new JsonObject { ["test"] = new JsonArray{ 1, 2, 3 } },
  new JsonObject { ["test"] = new JsonArray{ 1, 2, 3 } },
}

var patch = start.CreatePatch(target);

This results in the JSON Patch

1
2
3
4
5
6
7
[
  {"op":"replace","path":"/1/test","value":"test32132"},
  {"op":"remove","path":"/2/test"},
  {"op":"add","path":"/2/test1","value":"test321"},
  {"op":"replace","path":"/3/test/2","value":3},
  {"op":"add","path":"/4","value":{"test":[1,2,3]}}
]

This patch can be tested on the first object and should generate the second.

Other related features:

  • Generate reverse patches: target.CreatePatch(start)
  • Generate patches between .Net objects: myObject1.CreatePatch(myObject2)

Ahead of Time (AOT) compatibility

JsonPatch.Net v3 includes updates to support Native AOT applications. In order to take advantage of this, there are a few things you’ll need to do.

First, on your JsonSerializerContext, add the following attributes:

1
2
[JsonSerializable(typeof(JsonPatch))]
[JsonSerializable(typeof(PatchResult))]

It’s recommended that you create a single JsonSerializerOptions object (or a few if you need different configurations) and reuse it rather than creating them ad-hoc. When you create one, you’ll need to configure its TypeInfoResolverChain with your serializer context:

1
2
3
4
var serializerOptions = new()
{
    TypeInfoResolverChain = { MySerializerContext.Default }
};

You’re done. Congratulations.

Contents