Patching: JSON Patch Syntax

• Similar to other forms of patching, JSON Patches can be used by a client to swiftly change any number of documents without loading and editing the documents locally first.

• A series of JSON objects, each containing a patch operation and a document ID, are added to an ASP JsonPatchDocument object that is sent to the server for execution.

When are JSON Patches Used?

JSON Patches include no RQL or C# code, and offer a limited set of operations in relation to other patching methods.
Users may still prefer them over other methods when, for example -

• A client of multiple databases of different brands prefers broadcasting patches with a common syntax to all databases.
• It is easier for an automated process that builds and applies patches, to send JSON patches.

To run JSON patches -

• Use the Microsoft.AspNetCore.JsonPatch namespace from your code.
  E.g. using Microsoft.AspNetCore.JsonPatch;
• Create a JsonPatchDocument instance and append your patches to it.

• Pass your Json Patch Document to RavenDB's JsonPatchOperation operation to run the patches.

  • JsonPatchOperation Parameters

    Parameters	Type	Description
    id	string	The ID of the document we want to patch
    jsonPatchDocument	JsonPatchDocument	Patches document

Add Operation

Use the Add operation to add a document property or an array element.

• Method Parameters

  Parameters	Type	Description
  path	string	Path to the property we want to add
  value	object	Property value

• Code Sample - Add a document property
  

  var patchesDocument = new JsonPatchDocument();
  patchesDocument.Add("/PropertyName", "Contents");
  store.Operations.Send(new JsonPatchOperation(documentId, patchesDocument));

Remove Document Property

Use the Remove operation to remove a document property or an array element.

• Method Parameters

  Parameters	Type	Description
  path	string	Path to the property we want to remove

• Code Sample - Remove a document property
  

  patchesDocument = new JsonPatchDocument();
  patchesDocument.Remove("/PropertyName");
  store.Operations.Send(new JsonPatchOperation(documentId, patchesDocument));

Replace Document Property Contents

Use the Replace operation to replace the contents of a document property or an array element

• Method Parameters

  Parameters	Type	Description
  path	string	Path to the property whose contents we want to replace
  value	object	New contents

• Code Sample - Replace a document property
  

  patchesDocument = new JsonPatchDocument();
  // Replace document property contents with a new value (100)
  patchesDocument.Replace("/PropertyName", "NewContents");
  store.Operations.Send(new JsonPatchOperation(documentId, patchesDocument));

Copy Document Property Contents to Another Property

Use the Copy operation to copy the contents of one document property array element to another

• Method Parameters

  Parameters	Type	Description
  from	string	Path to the property we want to copy
  path	string	Path to the property we want to copy to

• Code Sample - Copy document property contents
  

  patchesDocument = new JsonPatchDocument();
  // Copy document property contents to another document property
  patchesDocument.Copy("/PropertyName1", "/PropertyName2");
  store.Operations.Send(new JsonPatchOperation(documentId, patchesDocument));

Move Document Property Contents to Another Property

Use the Move operation to move the contents of one document property or array element to another

• Method Parameters

  Parameters	Type	Description
  from	string	Path to the property whose contents we want to move
  path	string	Path to the property we want to move the contents to

• Code Sample - Move document property contents
  

  patchesDocument = new JsonPatchDocument();
  // Move document property contents to another document property
  patchesDocument.Move("/PropertyName1", "/PropertyName2");
  store.Operations.Send(new JsonPatchOperation(documentId, patchesDocument));

Test Patching Operation

Use the Test operation to verify patching operations.
If the test fails, all patching operations included in the patches document will be revoked and a RavenException exception will be thrown.

• Method Parameters

  Parameters	Type	Description
  path	string	Path to the property we want to test
  value	object	Value to compare path with

• Code Sample - Test Patching

patchesDocument = new JsonPatchDocument();
patchesDocument.Test("/PropertyName", "Value"); // Compare property contents with the value 
                                                // Revoke all patch operations if the test fails 
try
{
    store.Operations.Send(new JsonPatchOperation(documentId, patchesDocument));
}
catch (RavenException e)
{
    // handle the exception
}

The samples given above remain simple, showing how to manipulate document properties.
Note that JSON Patches have additional options, like the manipulation of array or list elements:

• Add an array element
  

  patchesDocument = new JsonPatchDocument();
  // Use the path parameter to add an array element
  patchesDocument.Add("/ArrayName/12", "Contents");
  store.Operations.Send(new JsonPatchOperation(documentId, patchesDocument));

You can learn more about additional JSON patching options in the JSON Patch RFC, among other resources.