Skip to main content

Patching: JSON Patch Syntax

JSON Patches​

  • 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.

Running 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

      ParametersTypeDescription
      idstringThe ID of the document we want to patch
      jsonPatchDocumentJsonPatchDocumentPatches document

Patch Operations​

Add Operation​

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

  • Method Parameters

    ParametersTypeDescription
    pathstringPath to the property we want to add
    valueobjectProperty 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

    ParametersTypeDescription
    pathstringPath 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

    ParametersTypeDescription
    pathstringPath to the property whose contents we want to replace
    valueobjectNew 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

    ParametersTypeDescription
    fromstringPath to the property we want to copy
    pathstringPath 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

    ParametersTypeDescription
    fromstringPath to the property whose contents we want to move
    pathstringPath 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

    ParametersTypeDescription
    pathstringPath to the property we want to test
    valueobjectValue 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
}

Additional JSON Patching Options​

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.