Writing JSONPath Expressions
ON THIS PAGE
JSONPath tool lets you analyse and selectively extract data from a JSON structure. JSONPath is similar to XPath for XML.
JSONPath uses JSONPath expressions to select elements from a JSON structure.
Let us take a very simple use case where we want to extract the event name from the following JSON document.
{
"event": {
"name": "agent",
"data": {
"name": "James Bond"
}
}
}
You can query for event name using following JSONPath expression
event.name
Supported Operators
JSONPath expressions support following operators
Operator | Description |
---|---|
$ | The root element to query. This starts all path expressions. |
@ | The current node being processed by a filter predicate. |
* | Wildcard. Available anywhere a name or numeric are required. |
.. | Deep scan. Available anywhere a name is required. |
.<name> | Dot-notated child |
[’<name>’ (, ‘<name>’)] | Bracket-notated child or children |
[<number> (, <number>)] | Array index or indexes |
[start:end] | Array slice operator |
[?(<expression>)] | Filter expression. Expression must evaluate to a boolean value. |
Functions
Functions can be invoked at the tail end of a path - the input to a function is the output of the path expression.
Following functions are supported
Function | Description | Output |
---|---|---|
min() | Provides the min value of an array of numbers | Double |
max() | Provides the max value of an array of numbers | Double |
avg() | Provides the average value of an array of numbers | Double |
stddev() | Deep scan. Available anywhere a name is required. | Double |
length() | Dot-notated child | Double |
Filter Operators
Filters are logical expressions used to filter arrays. A typical filter would be [?(@.age > 18)]
where @
represents the current item being processed. More complex filters can be created with logical operators &&
and ||
. String literals must be enclosed by single or double quotes ([?(@.color == 'blue')]
or [?(@.color == "blue")]
).
Operator | Description |
---|---|
== | left is equal to right (note that 1 is not equal to ‘1’) |
!= | left is not equal to right |
< | left is less than right |
> | left is greater than right |
>= | left is greater than or equal to right |
=~ | left matches regular expression [?(@.name =~ /foo.*?/i)] |
in | left exists in right [?(@.size in [‘S’, ‘M’])] |
nin | left does not exists in right |
subsetof | left is a subset of right [?(@.sizes subsetof [‘S’, ‘M’, ‘L’])] |
size | size of left (array or string) should match right |
empty | left (array or string) should be empty |
JSONPath expression examples
For the following JSON:
{
"event": {
"name": "Bond Movies",
"movies": [
{
"name": "Licence to Kill",
"star": "Timothy Dalton",
"rating": 6.6
},
{
"name": "GoldenEye",
"star": "Pierce Brosnan",
"rating": 7.2
},
{
"name": "Tomorrow Never Dies",
"star": "Pierce Brosnan",
"rating": 6.5
},
{
"name": "Skyfall",
"star": "Daniel Craig",
"rating": 7.8
}
]
}
}
JSONPath | Result |
---|---|
$ | Entire object |
$.event | Event object |
$.event[‘name’] | Event name |
$.event.name | Event name |
$..name | All names |
$.event.movies[0] | First movie |
$.event.[‘movies’]][0] | First movie |
$.event.movies[0,2] | First three movies |
$.event.movies[:2] | First two movies |
$.event.movies[-2:] | Last two movies |
$.event.movies[?(@.rating > 7)] | All movies with rating greater than 7 |
$.event.movies[?(@.star == ‘Pierce Brosnan’)] | All movies by Pierce Brosnan |
$.event.movies.length() | Number of movies |
What is Returned When?
JsonPath tries to automatically cast the result to the type expected by the invoker.
Following operators always return a list
- .. - a deep scan operator
- ?(
) - an expression - [
, (, )\] - multiple array indexes
Further Reading
Hevo uses Jayway JSONPath to evaluate JSONPath expressions. You can refer to JsonPath for the complete reference.