Using JSONMatch

JSONMatch is widely used in the patch mutation type when updating documents in gradient. All mutations types support JSONMatch at the root key level when targeting the operations. This means that a single set, unset, append or inc operation can easily target one or more values of the document, or use the powerful recursive filtering of JSONMatch to find the desired value of the document automatically.

General format

A JSONMatch path is an expression that, when evaluated, resolves to one or more locations in JSON document. A path can traverse object keys and arrays.


In this reference we will use the following example JSON object to extract data from:

  "name": "fred",
  "friends": [
      "name": "mork",
      "age": 40,
      "favoriteColor": "red"
      "name": "mindy",
      "age": 32,
      "favoriteColor": "blue"
      "name": "franklin",
      "favoriteColor": "yellow"
  "roles": ["admin", "owner"],
  "contactInfo": {
    "streetAddress": "42 Mountain Road",
    "state": {
    "shortName": "WY",
    "longName": "Wyoming"

Given the example document, these expressions can be evaluated:

"friends[*].name" → ["mork", "mindy", "franklin"] 
"friends[age > 35].name" → ["mork"] 
"friends[age > 30, favoriteColor == "blue"].name" → ["mork", "mindy"] 
"friends[age?].age" → [40, 32] 
"friends[0, 1].name""mork" 
"friends[0, 1].name" → ["mork", "mindy"] 
"friends[1:2].name" → ["mindy", "franklin"] 
"friends[0, 1:2].name" → ["mork", "mindy", "franklin"] 
"contactInfo.state[shortName, longName]" → ["WY", "Wyoming"] 
"friends.age[@ > 35]" → [35] 
"roles" → ["admin", "owner"] 
"roles[*]" → ["admin", "owner"] 
"[contactInfo.state.shortName, roles]" → ["WY", ["admin", "owner"]] 


A single key matches that key in an object. For example, name returns "fred".

Descent operator

The . operator descends into a key and selects a nested key. It has the format: key1.key2

For example:

This will match the `name` attribute in:

  "friend": {
    "name": "mork"

Recursive descent

The .. operator matches every value below the current selection descending through any objects, iterating over every array. Typical usage is to find a sub-object regardless of where it resides in an object. content.blocks..[key == "abc123"] will find the object having the attribute key equal to "abc123" wherever it resides inside the object or array at content.blocks.


Arrays can be subscripted with the [] operator. It has the formats:

"array[2]" → The second element of the array
"array[2, 3, 9]" → the second, third and ninth array element
"array[-1]" → the last array element
"array[1:9]" array element 1 through 9 (non inclusive)
"array[4:]" array element 4 through to the end of the array
"array[:4]" array elements from the start to element 4 of tha array (non inclusive)
"array[1, 4, 5:9, 12]" → union of array elements 1, 4, 5 to 9 and 12


Arrays can be filtered with constraints, e.g. friends[age == 32]. Constraints are separated by comma and are always a union ("or"), not an intersection.

Boolean operations

In its current implementation, JSONMatch do not support boolean operators && or ||, BUT essentially a union is the same as boolean or, and chaining constraints work the same as boolean and:

"numbers[@ < 50, @ > 60]": Select numbers that are < 50 OR > 60.

"numbers[@ > 20][@ < 30]": Select number that are > 20 AND < 30.

'employees[name == "John Smith", name == "Granny Smith"]': employees that have then name "John Smit" OR "Granny Smith".

Previous: PatchesNext: Assets