JSONPath is a query language for JSON that allows you to refer to a JSON object structure in the same way as XPath expressions do for XML documents. In ReadyAPI, you can apply JSONPath expressions to refer specific objects or elements in requests and responses, which is useful for assertions or property expansions that work with JSON objects.
Different ReadyAPI versions use different versions of the JSONPath library:
ReadyAPI 3.41.0 and later – JayWay JSONPath 2.7.0
ReadyAPI 2.3 - 3.40.2 – JayWay JSONPath 2.4.0
ReadyAPI 1.4.1 – 2.2 – JayWay JSONPath 2.0.0
ReadyAPI 1.1 – 1.4.0 – JayWay JSONPath 0.9.1
There are multiple ways to use JSONPath in ReadyAPI.
In functional tests:
Transfer properties
Use JSON objects as data sources
In security tests:
Get properties to use these in security scans
In virtual services:
Get request properties to compare them with a baseline within in accordance with the selected dispatch strategy
Overall ReadyAPI:
Create one of various assertions
Retrieve data to use in property expansions
A JSONPath expression describes the path to a single element or set of elements in a JSON structure. You can use any of the following notations:
Dot notation:
$.store.book[0].titleBracket notation:
$['store']['book'][0]['title']
The leading $ character represents the root object or array. It is optional and can be removed – so, $.object.element and object.element are basically the same expressions, as well as $.[0].attribute and [0].attribute.
The following table describes the JSONPath expressions that you can use in ReadyAPI:
Expression | Description |
|---|---|
| The root object or array. |
| Selects the NoteUse the latter notation if the name of the property includes special characters (for example, spaces), or begins with a character other than |
| Selects the n-th element from an array. Indexes start from 0. |
| Selects n1 and n2 array items. Returns a list. |
| Performs a deep scan for the specified property in all available objects. Always returns a list, even for a single match. |
| Wildcard. Selects all elements in an object or array, regardless of their names or indexes. For more information, see below. |
| Selects array items from n1 up to n2. The n2 element is not included in the selection. Remove n2 from the expression to select array items from n1 to the end of an array. Returns a list. |
| Selects the first n items of the array. Returns a list. |
| Selects the last n items of the array. Returns a list. |
| Filter. Selects all elements in an object or array that match the specified filter. Returns a list. |
| Used for filter expressions. Refers to the current node for further processing. |
Note
All of the JSONPath expressions (including property names and values) are case-sensitive.
Apply filters to JSON arrays and objects to get a subset of items that match the filter condition.
Important
In general, to create a filter expression, you need to place it after the path and enclose it in square brackets. For example:
$.store.book[?(@.price > 10)]Here, the @ character represents the current array item or object you want to process.
In addition, to refer properties located outside of the current object, add the $ character to the filter:
$.store.book[?(@.price > $.expensive)]It is also possible to create an expression that will match all items that have a specific property:
[?(@.isbn)] // Matches all the isbn properties regardless of which object these belong toThe following table contains all filter operators that you can use in various versions of ReadyAPI:
Operator | Description |
|---|---|
| Equals to. To use string values in the expression, enclose them in single quotes, not double quotes. For example, In ReadyAPI 2.3.0 and later: In ReadyAPI earlier than 2.3.0: |
| Not equal to. To use string values in the expression, enclose them in single quotes, not double quotes. For example, |
| Greater than. |
| Greater than or equal to. |
| Less than. |
| Less than or equal to. |
| Match a JavaScript regular expression. For example, use Not available in ReadyAPI versions earlier than 1.4.1. |
| A negative filter. For example, use Not available in ReadyAPI versions earlier than 1.4.1. |
| Logical AND. Allows to combine multiple filter expressions, for example: [?(@.type == 't-shirt' && @.amount > 3)]Not available in ReadyAPI versions earlier than 1.4.1. |
| Logical OR. Allows to combine multiple expressions, for example: [?(@.type == 't-shirt' || @.amount > 3)]Not available in ReadyAPI versions earlier than 1.4.1. |
| Matches items whose property has one of the specified values, for example: [?(@.size in ['S', 'M'])]Not available in ReadyAPI versions earlier than 2.3.0. |
| Matches items whose property does not have one of the specified values. Not available in ReadyAPI versions earlier than 2.3.0. |
| Matches items whose property has a value which is a subset of the specified array. For example: [?(@.sizes subsetof ['S', 'M', 'L'])]Not available in ReadyAPI versions earlier than 2.3.0. |
| Matches items whose property (string or array) has the specified size. Not available in ReadyAPI versions earlier than 2.3.0. |
| Matches items whose property (string or array) is empty. For example: [?(@.sizes empty false)]Not available in ReadyAPI versions earlier than 2.3.0. |
Wildcards are used to select all available elements within an object or an array. JSONpath uses the * symbol to indicate wildcards. You can use it both in basic expressions and those containing filters. For example:
$.store.*This expression will return all properties of the object object.
By default, this option is disabled for ReadyAPI dialogs that allow you to use JSONPath expressions, so you have to enable it before using the wildcard expressions. For example, in the JSONPath Match assertion configuration dialog:
 |
JSONPath expressions can not only return a single element but also a list of matching elements. For example, you have this JSON object:
{ "company_name": "ACME", "shops": [ { "address": "Sunrise Ave", "phone": "555-110-1234" }, { "address": "Hull St", "phone": "555-120-1234", } ] }You can call the JSONPath expression to fetch all phone numbers, which would look like this:
shops[*].phoneNote
Make sure to enable wildcards to use this expression in ReadyAPI.
After you call this expression, you will receive a list that contains two numbers:
[555-110-1234, 555-120-1234]This is not a JSON array, but a list of items where the
[]characters indicate the beginning and end of the list.When using the assertions that compare a property value to a list of values, specify a list of expected values enclosed in
[]and separated by a comma and single space:[beverages, 10, true, ["bottle", "can"], {"taste": "orange"}]Do not enclose standalone strings (like
beverages) in quotes, unless the quotes are part of the value – for example, use"pastry"to match"\"pastry\"".Do not use double quotes for element names and values. Use single quotes.
JSONPath expressions can return either a single value or an array, depending on the expression syntax:
Expression containing filters (
[?(filter)]and array slices ([start:end]always return arrays, even if the resulting array contains a single item. For example:$.section.fields.item[?(@.name=='My Field')].fldValue– will return an array even if the
fldValueelement has one value only. To get this value, add an index to the expression:$.section.fields.item[?(@.name=='My Field')].fldValue[0]Object wildcards will return an array only if the object has 2 or more properties. Otherwise, these will return a value of the single property (this value will keep the initial type). For example, assuming you need to obtain properties of the following object:
{ "section": { "first_subsection": { "name": "titular" }, "second_subsection": { "name": "secondary", "contains_images": true } } }The following expression will return a
titularstring:$.section.first_subsection.* // The first_subsection element has a single propertyThe following expression will return an array:
$.section.second_subsection.* // Returns ["name": "secondary", "contains_images": true"]The behavior of the array wildcards (
arr[*]) depends on which ReadyAPI version you use:In ReadyAPI 2.3.0 and later: Array wildcards should always return an array. For the preceding example, the following expression:
$.section.first_subsection[*]– will return an array:
["name": "titular"]In ReadyAPI 1.4.1 – 2.2.0: Array wildcards return an array only if the original array includes more than 2 items. For the arrays including a single item, the results may vary depending on the item type.
For example, for the following objects:
{ "section": ["content"], "second_section": [ {"number": 2} ] }the JSONPath expressions will work as follows:
$.section[*] = content // A string $.second_section[*] = [ {"number": 2} ] // An array
For these examples, we will use a modified version of JSON from the JayWay JSONPath GitHub repository:
{
"store": {
"book": [
{
"category": "history",
"author": "Arnold Joseph Toynbee",
"title": "A Study of History",
"price": 5.50
},
{
"category": "poem",
"author": "Aneirin",
"title": "Y Gododdin",
"price": 17.00
},
{
"category": "fiction",
"author": "James Joyce",
"title": "Finnegans Wake",
"isbn": "9788804677628",
"price": 15.99
},
{
"category": "fiction",
"author": "Emily Bronte",
"title": "Wuthering Heights",
"isbn": "0-486-29256-8",
"price": 3.30
}
],
"bicycle": {
"color": "purple",
"price": 25.45
}
},
"expensive": 10
}
Notice
Make sure to enable wildcards to use this expression in ReadyAPI.
Task | Expression | Result |
|---|---|---|
To retrieve all direct properties of the | $.store.* | |
To find out the bicycle's color | $.store.bicycle.color |
|
To learn the prices of all items in the store | $.store..price
$..priceNoteMake sure to enable wildcards to use this expression in ReadyAPI. |
|
To retrieve information on all books | $.store.book[*]
$..book[*]NoteMake sure to enable wildcards to use this expression in ReadyAPI. | |
To find out the titles of all books | $..book[*].titleNoteMake sure to enable wildcards to use this expression in ReadyAPI. |
|
To retrieve information on a first book in the catalog | $..book[0] | [{"category": "history", "author": "Arnold Joseph Toynbee", "title": "A Study of History", "price": 5.50}] |
To retrieve the title of the first book in the catalog | $..book[0] |
|
To retrieve the titles of the first two books | $..book[0,1].title
$..book[:2].title |
|
To retrieve the title of the last book | $..book[-1:].title |
NoteThe result is a list, because the |
To retrieve the titles of all books by James Joyce | $..book[?(@.author=='James Joyce')].title |
NoteThe result is a list, because filters always return lists. |
To retrieve all books that have the | $..book[?(@.isbn)] | |
To retrieve all fiction and poetry books | $..[?(@.category == 'fiction' || @.category == 'poem')]In ReadyAPI 2.3.0 and later you can also use the expression with the $..book[?(@.category in ['fiction', 'poem'])] | |
To retrieve all books without the | $..book[?(!@.isbn)] | |
To retrieve all books cheaper than 10 | $..[?(@.price < 10)] | |
To retrieve all expensive books | $..[?(@.price > $.expensive)] | |
To retrieve all books whose author's name ends with Joyce | NoteThis search is case-sensitive, so ensure the use of correct letter casing for accurate results. $..book[?(@.author =~ /.*Joyce/i)] | |
To retrieve the JSON structure | $..* NoteMake sure to enable wildcards to use this expression in ReadyAPI. | This returns all members of the JSON structure beneath the root, including child objects and separate properties, combined into a single array. |