Support )

! AlertSite Documentation
AlertSite Documentation / Monitors / API Monitoring / API Endpoint Monitors
" Introducing AlertSite

" JSONPath Syntax

!

!
Tutorials

! Monitors ! Last modi!ed on August 16, 2021

"
" Website Monitoring
#
!

! API Monitoring JSONPath is a query language for JSON, similar to XPath for XML. AlertSite API endpoint monitors
let you use JSONPath in assertions to specify the JSON !elds that need to be veri!ed. "
$ ! API Endpoint Monitors
!

Create API Monitor

%
!

!
Create From OpenAPI (Swagger) JSONPath notation
&
!

!
Assertions
A JSONPath expression speci!es a path to an element (or a set of elements) in a JSON structure.
!
Variables Paths can use the dot notation:

!
Monitor Settings
$.[Link][0].title
!
Convert to SoapUI
or the bracket notation:
!
JSONPath Syntax

" SoapUI Monitors $['store']['book'][0]['title']

!
ReadyAPI Versions Used by AlertSite
The leading $ represents the root object or array and can be omitted. For example, $.[Link]
" Mobile Monitoring and [Link] are the same, and so are $[0].status and [0].status .
" Email Monitoring Other syntax elements are described below.
" FTP Monitoring
Expression Description
" Network Monitors
$ The root object or array.
" SLA Monitoring
.property Selects the speci!ed property in a parent object.
" Metrics
['property'] Selects the speci!ed property in a parent object. Be sure to put
!
Site Seals single quotes around the property name.

' " Con!guring Monitors Tip: Use this notation if the property name contains special
characters such as spaces, or begins with a character other than
" Dashboards
( A..Za..z_ .
" Alerts
[n] Selects the n-th element from an array. Indexes are 0-based.

[index1,index2,…] Selects array elements with the speci!ed indexes. Returns a list.

..property Recursive descent: Searches for the speci!ed property name

recursively and returns an array of all values with this property
name. Always returns a list, even if just one property is found.
* Wildcard selects all elements in an object or an array, regardless
of their names or indexes. For example, address.* means all
properties of the address object, and book[*] means all items of
the book array.

[start:end] Selects array elements from the start index and up to, but not
[start:] including, end index. If end is omitted, selects all elements from
start until the end of the array. Returns a list.

[:n] Selects the !rst n elements of the array. Returns a list.

[-n:] Selects the last n elements of the array. Returns a list.

[?(expression)] Filter expression. Selects all elements in an object or array that

match the speci!ed !lter. Returns a list.
[(expression)] Script expressions can be used instead of explicit property names
or indexes. An example is [(@.length-1)] which selects the last
item in an array. Here, length refers to the length of the current
array rather than a JSON !eld named length .

@ Used in !lter expressions to refer to the current node being

processed.

Notes:

JSONPath expressions, including property names and values, are case-sensitive.

Unlike XPath, JSONPath does not have operations for accessing parent or sibling nodes
from the given node.

Filters
Filters are logical expressions used to !lter arrays. An example of a JSONPath expression with a
!lter is

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

where @ represents the current array item or object being processed. Filters can also use $ to
refer to the properties outside of the current object:

$.[Link][?(@.price < $.expensive)]

An expression that speci!es just a property name, such as [?(@.isbn)] , matches all items that
have this property, regardless of the value.

Below are the operators that can be used in !lters.

Supported operators depend on the monitor playback engine.

Operator Description
== Equals to. String values must be enclosed in single quotes (not double
quotes): [?(@.color=='red')] .

Note: Number to string comparison works di"erently depending on the

playback engine. In TestEngine, 1 does not equal '1' . In ReadyAPI 1.9 and
earlier, 1 equals '1' .

!= Not equal to. String values must be enclosed in single quotes:

[?(@.color!='red')] .

> Greater than.

>= Greater than or equal to.

< Less than.

<= Less than or equal to.

=~ Matches a JavaScript regular expression. For example,

[?(@.description =~ /cat.*/i)] matches items whose description starts with
cat (case-insensitive).

Note: Not supported if ReadyAPI 1.1 is used as the playback engine.

! Used to negate a !lter: [?(!@.isbn)] matches items that do not have the
isbn property.

Note: Not supported if ReadyAPI 1.1 is used as the playback engine.

&& Logical AND, used to combine multiple !lter expressions:

[?(@.category=='fiction' && @.price < 10)]

|| Logical OR, used to combine multiple !lter expressions:

[?(@.category=='fiction' || @.price < 10)]

Note: Not supported if ReadyAPI 1.1 is used as the playback engine.

in Checks if the left-side value is present in the right-side list. Similar to the SQL
IN operator. String comparison is case-sensitive.

[?(@.size in ['M', 'L'])]

[?('S' in @.sizes)]

Note: Supported only by the TestEngine playback engine.

nin Opposite of in . Checks that the left-side value is not present in the right-side
list. String comparison is case-sensitive.

[?(@.size nin ['M', 'L'])]

[?('S' nin @.sizes)]

Note: Supported only by the TestEngine playback engine.

subsetof Checks if the left-side array is a subset of the right-side array. The actual
order of array items does not matter. String comparison is case-sensitive. An
empty left-side array always matches.

For example:

[?(@.sizes subsetof ['M', 'L'])] – matches if sizes is ['M'] or ['L']

or ['L', 'M'] but does not match if the array has any other elements.

[?(['M', 'L'] subsetof @.sizes)] – matches if sizes contains at least

'M' and 'L' .

Note: Supported only by the TestEngine playback engine.

contains Checks if a string contains the speci!ed substring (case-sensitive), or an array

contains the speci!ed element.

[?(@.name contains 'Alex')]

[?(@.numbers contains 7)]

[?('ABCDEF' contains @.character)]

Note: Supported only by the TestEngine playback engine.

size Checks if an array or string has the speci!ed length.

[?(@.name size 4)]

Note: Supported only by the TestEngine playback engine.

empty true Matches an empty array or string.

[?(@.name empty true)]

Note: Supported only by the TestEngine playback engine.

empty false Matches a non-empty array or string.

[?(@.name empty false)]

Note: Supported only by the TestEngine playback engine.

Examples
For these examples, we will use a modi!ed version of JSON from
[Link]

{
"store": {
"book": [
{
"category": "reference",
"author": "Nigel Rees",
"title": "Sayings of the Century",
"price": 8.95
},
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fiction",
"author": "J.R.R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycle": {
"color": "red",
"price": 19.95
}
},
"expensive": 10
}

In all these examples, the leading $. is optional and can be omitted.

Expression Meaning
$.store.* All direct properties of store (not recursive).

$.[Link] The color of the bicycle in the store.

Result: red

$.store..price The prices of all items in the store.

$..price
Result: [8.95, 8.99, 22.99, 19.95]

$.[Link][*] All books in the store.

$..book[*]

$..book[*].title The titles of all books in the store.

Result:
[Sayings of the Century,
Moby Dick,
The Lord of the Rings]

$..book[0] The !rst book.

Result:

[
{
"category":"reference",
"author":"Nigel Rees",
"title":"Sayings of the
Century",
"price":8.95
}
]

$..book[0].title The title of the !rst book.

Result: Sayings of the Century

$..book[0,1].title The titles of the !rst two books.

$..book[:2].title
Result: [Sayings of the Century, Moby Dick]

$..book[-1:].title The title of the last book.

$..book[(@.length-1)].title
Result: [The Lord of the Rings]

The result is a list, because [-n:] always

returns lists.

$..book[?(@.author=='J.R.R. Tolkien')].title The titles of all books by J.R.R. Tolkien (exact

match, case-sensitive).

Result: [The Lord of the Rings]

The result is a list, because !lters always

return lists.

$..book[?(@.isbn)] All books that have the isbn property.

$..book[?(!@.isbn)] All books without the isbn property.

$..book[?(@.price < 10)] All books cheaper than 10.

$..book[?(@.price > $.expensive)] All expensive books.

$..book[?(@.author =~ /.*Tolkien/i)] All books whose author name ends with

Tolkien (case-insensitive).
$..book[?(@.category == 'fiction' || All !ction and reference books.
@.category == 'reference')]

$..* All members of the JSON structure beneath

the root (child objects, individual property
values, array items), combined into an array.

Considerations for JSONPath expressions that return multiple

elements
JSONPath queries can return not just a single element, but also a list of matching elements. For
example, given this JSON:

{
"name": "Rose Kolodny",
"phoneNumbers": [
{
"type": "home",
"number": "954-555-1234"
},
{
"type": "work",
"number": "754-555-5678"
}
]
}

the JSONPath expression

phoneNumbers[*].number

returns a list containing two phone numbers:

[954-555-1234, 754-555-5678]

Note that this is not a JSON array, it is just a comma-separated list of items where [ ] indicates
the beginning and end of the list.

When using “equals” assertions against a list of matches, specify a list of expected values
enclosed in [ ] and separated by a comma and one space:

[apples, 15, false, ["foo","bar"], {"status":"ok"}]

Standalone strings (like apples ) should not have enclosing quotes, unless the quotes are part of
the value.

Example

Values that are JSON arrays and objects keep inner quotes, but are mini!ed with no spaces
between their items: ["foo","bar"] , not [ "foo" , "bar" ] .

FAQ
How can I check that my JSONPath syntax is valid?

If you have ReadyAPI 1.9, you can create a test for your API endpoint, add a JSONPath Match
assertion and test the syntax in the assertion editor there.

Otherwise, you can use [Link] and check the results on the Jayway tab.
However, the syntax used on this site may be slightly di"erent from the one used in AlertSite.

See Also
API Assertions
Creating an API Endpoint Monitor
API Endpoint Monitor Settings

Explore SmartBear Products

AlertSite Collaborator ReadyAPI SwaggerHub

!

AQTime Pro Cucumber for Jira SoapUI TestComplete

!

BitBar CucumberStudio Swagger TestEngine

!

Capture for Jira LoadNinja TestLeft

!
!

CrossBrowserTesting Zephyr
!
!

About Us | Careers | Solutions | Partners

Contact Us | +1 617-684-2600 USA | +353 91 398300 EUR | +61 391929960 AUS

© 2021 SmartBear Software. All Rights Reserved.

Privacy | Terms of Use | Site Map | Website Terms of Use ! " # $