JSONPath Reference

Applies to ReadyAPI 3.56, last modified on November 21, 2024

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.

Supported JSONPath libraries

Different ReadyAPI versions use different versions of the JSONPath library:

Try it out

There are multiple ways to use JSONPath in ReadyAPI.

JSONPath notation

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].title
  • Bracket 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.

Expression syntax

The following table describes the JSONPath expressions that you can use in ReadyAPI:

Expression Description
$ The root object or array.
object.property
['object'].['property']
Selects the property property in the object object.
Note: Use the latter notation if the name of the property includes special characters (for example, spaces), or begins with a character other than A..Za..z_.
[n] Selects the n-th element from an array. Indexes start from 0.
[n1, n2] Selects n1 and n2 array items. Returns a list.
..property 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.
[n1:n2]
[n1:]
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.
[:n] Selects the first n items of the array. Returns a list.
[-n:] Selects the last n items of the array. Returns a list.
[?(expression)] 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.

Filters

Apply filters to JSON arrays and objects to get a subset of items that match the filter condition.

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 to

The 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, [?(@.color=='red')].
In ReadyAPI 2.3.0 and later: 1 is not equal to '1'.
In ReadyAPI earlier than 2.3.0: 1 is equal to '1'.
!= Not equal to.
To use string values in the expression, enclose them in single quotes, not double quotes. For example, [?(@>color!='red')].
> Greater than.
>= Greater than or equal to.
< Less than.
<= Less than or equal to.
=~ Match a JavaScript regular expression. For example, use [?(@.name =~ /cat.*/i] to find all items that have names starting with cat (including cat, catechesis, caterpillar, and so on).
Not available in ReadyAPI versions earlier than 1.4.1.
! A negative filter. For example, use [?([email protected])] to match all items that do not have the color property.
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.
in 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.
nin Matches items whose property does not have one of the specified values.
Not available in ReadyAPI versions earlier than 2.3.0.
subsetof 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.
size Matches items whose property (string or array) has the specified size.
Not available in ReadyAPI versions earlier than 2.3.0.
empty 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

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:

The wildcards enabled in the JSONPath Match assertion configuration dialog

Click the image to enlarge it.

Usage notes and considerations

  • JSONPath expressions can not only return a single element, but also a list of matching elements. For example, you have this JSON object:

    Example

    You can call the JSONPath expression to fetch all phone numbers, which would look like this:

    shops[*].phone

    Note: 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 fldValue element 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:

      Example

      The following expression will return a titular string:

      $.section.first_subsection.*

      // The first_subsection element has a single property

      The 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

Examples

For these examples, we will use a modified version of JSON from the JayWay JSONPath GitHub repository:

Example

Use the following expression:

$.store.*

Make sure to enable wildcards to use this expression in ReadyAPI.

Use the following expression:

$.store.bicycle.color

Result: purple.

Use one of the following expressions:

$.store..price
$..price

Make sure to enable wildcards to use this expression in ReadyAPI.

Result: [5.50, 17.00, 15.99, 3.30, 25.45].

Use one of the following expressions:

$.store.book[*]
$..book[*]

Make sure to enable wildcards to use this expression in ReadyAPI.

Use the following expression:

$..book[*].title

Result: [A Study of History, Y Gododdin, Finnegans Wake, Wuthering Heights].

Make sure to enable wildcards to use this expression in ReadyAPI.

Use the following expression:

$..book[0]

Result:

[{"category": "history", "author": "Arnold Joseph Toynbee", "title": "A Study of History", "price": 5.50}]

Use the following expression:

$..book[0]

Result: A Study of History.

Use one of the following expressions:

$..book[0,1].title
$..book[:2].title

Result: [A Study of History, Y Gododdin].

Use the following expression:

$..book[-1:].title

Result: [Wuthering Heights].

Note: The result is a list, because the [-n:] expression always returns lists.

Use the following expression (exact match, case sensitive):

$..book[?(@.author=='James Joyce')].title

Result: [Finnegans Wake].

Note: The result is a list, because filters always return lists.

Use the following expression:

$..book[?(@.isbn)]

Use the following expression:

$..[?(@.category == 'fiction' || @.category == 'poem')]

In ReadyAPI 2.3.0 and later you can also use the expression with the in filter:

$..book[?(@.category in ['fiction', 'poem'])]

Use the following expression:

$..book[?([email protected])]

Use the following expression:

$..[?(@.price < 10)]

Use the following expression:

$..[?(@.price > $.expensive)]

Use the following expression (case insensitive):

$..book[?(@.author =~ /.*Joyce/i)]

Use the following expression:

$..*

This returns all members of the JSON structure beneath the root, including child objects and separate properties, combined into a single array.

Make sure to enable wildcards to use this expression in ReadyAPI.

See Also

Property Content Assertions
Property Expansion
Testing APIs

Highlight search results