Skip to main content

​
Extracting data with JSONPath

WireMock Cloud provides the jsonPath helper which will extract values from a JSON document using the JSONPath expression language. Similar in concept to XPath, JSONPath permits selection of individual values or sub-documents via a query expression. For example, given the JSON 
{
  "outer": {
    "inner": "Stuff"
  }
}
The following will render “Stuff” into the output: 
{{jsonPath request.body '$.outer.inner'}}
And for the same JSON the following will render { "inner": "Stuff" }: 
{{jsonPath request.body '$.outer'}}

​
Iterating over JSON elements

The jsonPath helper outputs a “one or many” collection, which can either be printed directly, or passed to further helpers such as each or join. For instance, given a request body of the form: 
{
  "things": [
    {
      "id": 1
    },
    {
      "id": 2
    },
    {
      "id": 3
    }
  ]
}
And the following response body template: 
{{#each (jsonPath request.body '$.things') as |thing|}}
thing: {{{thing.id}}}{{/each}}
The response body will contain: 
thing: 1
thing: 2
thing: 3
The above will only work if the JSONPath expression selects an array from the request JSON. However, each can also be used to iterate over maps/objects, so given the request JSON: 
{
  "things": {
    "one": 1,
    "two": 2,
    "three": 3
  }
}
And the template: 
{{#each (jsonPath request.body '$.things') as |value key|}}
{{{key}}}={{{value}}}{{/each}}
The output would contain: 
one=1
two=2
three=3

​
Adding to a JSON Array

The jsonArrayAdd helper allows you to append an element to an existing json array. Its simplest form just takes two parameters, the array to append to and the item to be added: 
{{jsonArrayAdd existingArray newItem}}
The above template will produce the following JSON: 
[
    {
        "id": 123,
        "name": "alice"
    },
    {
        "id": 321,
        "name": "sam"
    }
]
You can also use it in block form to parse the contents of the block as the new item to add: 
{{#jsonArrayAdd existingArray}}
{
  "id": 321,
  "name": "sam"
}
{{/jsonArrayAdd}}
It may be convenient to default the array to an empty array if it does not exist: 
{{#jsonArrayAdd (val existingArray or='[]')}}
{
  "id": 321,
  "name": "sam"
}
{{/jsonArrayAdd}}
The number of items in the array can be limited by using the maxItems parameter: 
{{#assign 'existingArray'}}
[
    {
        "id": 123,
        "name": "alice"
    },
    {
        "id": 321,
        "name": "sam"
    }
]
{{/assign}}

{{#jsonArrayAdd existingArray maxItems=2}}
{
    "id": 456,
    "name": "bob"
}
{{/jsonArrayAdd}}
The above template will produce the following JSON. The first item in the array has been removed to maintain the number of items in the array as specified by the maxItems parameter: 
[
  {
    "id": 321,
    "name": "sam"
  },
  {
    "id": 456,
    "name": "bob"
  }
]
You can add arrays to the existing json array using this helper: 
{{#assign 'existingArray'}}
[
    {
        "id": 123,
        "name": "alice"
    },
    {
        "id": 321,
        "name": "sam"
    }
]
{{/assign}}

{{#jsonArrayAdd existingArray}}
[
    {
        "id": 456,
        "name": "bob"
    }
]
{{/jsonArrayAdd}}
The above template will produce the following JSON: 
[
  {
    "id": 123,
    "name": "alice"
  },
  {
    "id": 321,
    "name": "sam"
  },
  [
    {
      "id": 456,
      "name": "bob"
    }
  ]
]
If you want the end result to be a single json array, you can use the flatten attribute: 
{{#assign 'existingArray'}}
[
    {
        "id": 123,
        "name": "alice"
    },
    {
        "id": 321,
        "name": "sam"
    }
]
{{/assign}}

{{#jsonArrayAdd existingArray flatten=true}}
[
    {
        "id": 456,
        "name": "bob"
    }
]
{{/jsonArrayAdd}}
The above template will produce the following JSON: 
[
  {
    "id": 123,
    "name": "alice"
  },
  {
    "id": 321,
    "name": "sam"
  },
  {
    "id": 456,
    "name": "bob"
  }
]
You can use the jsonArrayAdd helper to add items to a nested array. This is achieved using the jsonPath property and referencing the array you want to add an item to: 
{{#assign 'existingArray'}}
[
    {
        "id": 123,
        "names":["alice", "sam"]
    },
    {
        "id": 321,
        "names":["fred", "neil"]
    }
]
{{/assign}}

{{#assign 'itemToAdd'}}"bob"{{/assign}}

{{jsonArrayAdd existingArray itemToAdd jsonPath='$[0].names'}}
The above template will produce the following JSON: 
[
  {
    "id": 123,
    "names": [ "alice", "sam", "bob" ]
  },
  {
    "id": 321,
    "names": [ "fred", "neil" ]
  }
]

​
Removing from a JSON Array or Object

The jsonRemove helper allows you to remove an element from an existing json array, or remove a key from an existing json object, by identifying it using a json path expression. For instance, given an existing array like this: 
{{#assign 'existingArray'}}
[
  { "id": 456, "name": "bob"},
  { "id": 123, "name": "alice"},
  { "id": 321, "name": "sam"}
]
{{/assign}}
application of this helper, which selects the object with id 123: 
{{jsonRemove existingArray '$.[?(@.id == 123)]'}}
will return this array: 
[
  { "id": 456, "name": "bob"},
  { "id": 321, "name": "sam"}
]
Given an object like this: 
{{#assign 'existingObject'}}
{ "id": 456, "name": "bob"}
{{/assign}}
application of this helper, which selects the key name: 
{{jsonRemove existingObject '$.name'}}
will return this object: 
{ "id": 456 }

​
Merging JSON objects

The jsonMerge helper allows you to merge two json objects. Merging will recurse into any common keys where the values are both objects, but not into any array values, where the value in the second object will overwrite that in the first. Given these two objects: 
{{#assign 'object1'}}
{
  "id": 456, 
  "forename": "Robert",
  "surname": "Smith",
  "address": {
    "number": "12"
  },
  "hobbies": [ "chess", "football" ]
}
{{/assign}}
{{#assign 'object2'}}
{
  "name": "Robert",
  "nickname": "Bob",
  "address": {
    "street": "High Street"
  },
  "hobbies": [ "rugby" ]
}
{{/assign}}

{{jsonMerge object1 object2}}
will return this object: 
{
  "id": 456,
  "forename": "Robert",
  "surname": "Smith",
  "nickname": "Bob",
  "address": {
    "number": "12",
    "street": "High Street"
  },
  "hobbies": [ "rugby" ]
}
Like the jsonArrayAdd helper, the second object can be provided as a block: 
{{#jsonMerge object1}}
{
  "name": "Robert",
  "nickname": "Bob",
  "address": {
    "street": "High Street"
  },
  "hobbies": [ "rugby" ]
}
{{/jsonMerge}}

​
Removing attributes

The jsonMerge helper has an optional removeNulls parameter which, when set to true will remove any attributes from the resulting JSON that have null values in the second JSON document. So for instance, given the following template: 
{{#assign 'object1'}}
{
    "keepMe": 1,
    "removeMe": 2
}
{{/assign}}

{{#jsonMerge object1 removeNulls=true}}
{
    "removeMe": null
}
{{/jsonMerge}}
The resulting JSON would be: 
{
    "keepMe": 1
}

​
Formatting JSON

The formatJson helper allows you to output JSON in either a pretty or a compact format. The default is pretty: 
{{#assign 'object1'}}
{"id": 456,
     "forename": "Robert", "surname": "Smith",
  "address": {
    "number": "12"
},
"hobbies": [ "chess", 
"football" ]
}
{{/assign}}
{{formatJson object1}}
emits: 
{
  "id" : 456,
  "forename" : "Robert",
  "surname" : "Smith",
  "address" : {
    "number" : "12"
  },
  "hobbies" : [ "chess", "football" ]
}
Whereas 
{{formatJson object1 format='compact'}}
emits 
{"id":456,"forename":"Robert","surname":"Smith","address":{"number":"12"},"hobbies":["chess","football"]}
The json to format can also be supplied as a block body: 
{{#formatJson}}
{"id": 456,
     "forename": "Robert", "surname": "Smith",
  "address": {
    "number": "12"
},
"hobbies": [ "chess", 
"football" ]
}
{{/formatJson}}

​
Sorting JSON Arrays

The jsonSort helper allows you to specify a field within a JSON array to sort by. The field is referenced using a JSON path expression, and all sort field values must be of the same comparable type (Number, String, or Boolean). For example: 
{{#assign 'jsonArray'}}
[
    {
        "id": 123,
        "name": "sam"
    },
    {
        "id": 321,
        "name": "alice"
    }
]
{{/assign}}

{{jsonSort jsonArray '$[*].name'}}
The above template will produce the following JSON: 
[
  {
    "id": 321,
    "name": "alice"
  },
  {
    "id": 123,
    "name": "sam"
  }
]
The order of the sorting is ascending (asc) by default. This can be changed by supplying desc for the order parameter. For example: 
{{#assign 'jsonArray'}}
[
    {
        "id": 123,
        "name": "sam"
    },
    {
        "id": 321,
        "name": "alice"
    }
]
{{/assign}}

{{jsonSort jsonArray '$[*].id' order='desc'}}
The above template will produce the following JSON: 
[
  {
    "id": 321,
    "name": "alice"
  },
  {
    "id": 123,
    "name": "sam"
  }
]
The array being referenced in the JSON path expression must be an array, but it doesn’t have to be a top-level array. For example: 
{{#assign 'jsonArray'}}
{"users":[{"name":"fred"},{"name":"bob"}]}
{{/assign}}

{{jsonSort jsonArray '$.users[*].name'}}
The above template will produce the following JSON: 
{"users":[{"name":"bob"},{"name":"fred"}]}
Even though all sort field values must be of the same comparable type (Number, String, or Boolean), this equally works for dates where they can be compared as strings. For example: 
{{#assign 'jsonArray'}}
[{"id":1,"created":"2025-03-15T14:30:00Z"},{"id":2,"created":"2025-01-10T09:15:00Z"},{"id":3,"created":"2025-12-01T18:45:00Z"}]
{{/assign}}

{{jsonSort jsonArray '$[*].created'}}
The above template will produce the following JSON: 
 [{"id":2,"created":"2025-01-10T09:15:00Z"},{"id":1,"created":"2025-03-15T14:30:00Z"},{"id":3,"created":"2025-12-01T18:45:00Z"}]
Simple arrays can also be sorted using the jsonSort helper: 
{{#assign 'jsonArray'}}
["charlie","alice","bob"]
{{/assign}}

{{jsonSort jsonArray '$[*]'}}
The above template will produce the following JSON: 
["alice","bob","charlie"]
You can also refernece arrays in a specific index position using the jsonPath parameter: 
{{#assign 'jsonArray'}}
[{"items":[{"price":30},{"price":10},{"price":20}]},{"items":[{"price":100},{"price":50}]}]
{{/assign}}

{{jsonSort jsonArray '$[0].items[*].price'}}
The above template will produce the following JSON: 
[{"items":[{"price":10},{"price":20},{"price":30}]},{"items":[{"price":100},{"price":50}]}]

​
Handling null when sorting

The jsonSort helper allows you to sort on a field that can be missing or null. When sorting, missing fields are treated as null. By default, nulls are added to the beginning of the sorted array: 
{{#assign 'jsonArray'}}
[{"id":1,"name":"alice"},{"id":2},{"id":3,"name":"bob"}]
{{/assign}}

{{jsonSort jsonArray '$[*].name'}}
The above template will produce the following JSON: 
[{"id":2},{"id":1,"name":"alice"},{"id":3,"name":"bob"}]
This can be changed by supplying a nulls parameter and setting the value to last - nulls='last'. This will move nulls to the end of the sorted array: 
{{#assign 'jsonArray'}}
[{"id":1,"name":"alice"},{"id":2},{"id":3,"name":"bob"}]
{{/assign}}

{{jsonSort jsonArray '$[*].name' nulls='last'}}
The above template will produce the following JSON: 
[{"id":1,"name":"alice"},{"id":3,"name":"bob"},{"id":2}]
The nulls parameter can also be set to first or last.

​
Stable Sorting

The jsonSort helper provides a ‘stable’ sort where the order of equal values are preserved. For example, sorting on a field that contains duplicate values will maintain the order within the array. This is demonstrated in the following example: 
{{#assign 'jsonArray'}}
[{"id":"a","score":100},{"id":"b","score":50},{"id":"c","score":50},{"id":"d","score":25},{"id":"e","score":50}]""";
{{/assign}}

{{jsonSort jsonArray '$[*].score'}}
The above template will produce the following JSON where the order of the duplicate items is preserved: 
[{"id":"d","score":25},{"id":"b","score":50},{"id":"c","score":50},{"id":"e","score":50},{"id":"a","score":100}]

​
Reading object as JSON

The parseJson helper will take the string value of the provided variable (or the contents of the block) and parse it into an object or array, and assign it to the given variable. e.g. 
{{#parseJson 'newVariableName'}}
    [ "shoes", "socks" ]
{{/parseJson}}
will add an array called newVariableName that can be used in subsequent helpers. The contents to parse can also be supplied inline: 
{{#assign 'inputString'}}
    [ "shoes", "socks" ]
{{/assign}}
{{parseJson inputString 'newVariableName'}}
If no variable name is supplied the result of the parsing is output.

​
Writing data as a JSON string

The toJson helper will convert any object into a JSON string. 
{{toJson (array 1 2 3)}}
emits 
[ 1, 2, 3 ]