JSONPath Reference

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

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:

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:

It is also possible to create an expression that will match all items that have a specific property:

Filter Syntax

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:

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:

Click the image to enlarge it.

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

  Example

  ExampleExample

  {
    "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[*].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

    ExampleExample

    {
      "section": {
        "first_subsection": {
          "name": "titular"
        },
        "second_subsection": {
          "name": "secondary",
          "contains_images": true
        }
      }
    }

    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

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

Example

ExampleExample

{
  "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
}

To retrieve all direct properties of the store object

To find out the bicycle’s color

To learn the prices of all items in the store

To retrieve information on all books

To find out the titles of all books

To retrieve information on a first book in the catalog

To retrieve the title of the first book in the catalog

To retrieve the titles of the first two books

To retrieve the title of the last book

To retrieve the titles of all books by James Joyce

To retrieve all books that have the isbn property

To retrieve all fiction and poetry books

To retrieve all books without the isbn property

To retrieve all books cheaper than 10

To retrieve all expensive books

To retrieve all books whose author’s name ends with Joyce

To retrieve the JSON structure