4 JSONPath functionality

Overview

This section outlines the supported JSONPath functionality within item value preprocessing steps.

JSONPath is composed of segments separated by dots. A segment can take the form of a simple word, representing a JSON value name, the wildcard character (*), or a more intricate construct enclosed within square brackets. The dot before a bracketed segment is optional and can be omitted.

See also: Escaping special characters from LLD macro values in JSONPath.

Supported segments

To find a matching segment ignoring its ancestry (detached segment), it must be prefixed with two dots (..). For example, $..name or $..['name'] return values of all name properties.

Matched element names can be extracted by adding a tilde (~) suffix to the JSONPath. It returns the name of the matched object or an index in string format of the matched array item. The output format follows the same rules as other JSONPath queries - definite path results are returned 'as is', and indefinite path results are returned in an array. However, there is minimal value in extracting the name of an element that matches a definitive path, as it is already known.

Filter expression

The filter expression is an arithmetical expression in infix notation.

Supported operands:

Supported operators:

Functions

Functions can be used at the end of JSONPath. Multiple functions can be chained if the preceding function returns value that is accepted by the following function.

Supported functions:

JSONPath aggregate functions accept quoted numeric values. These values are automatically converted from strings to numeric types when aggregation is needed. Incompatible input will cause the function to generate an error.

Output value

JSONPaths can be divided into definite and indefinite paths. A definite path can return only null or a single match. An indefinite path can return multiple matches: JSONPaths with detached, multiple name/index lists, array slices, or expression segments. However, when a function is used, the JSONPath becomes definite, as functions always output a single value.

A definite path returns the object/array/value it is referencing. In contrast, an indefinite path returns an array of the matched objects/arrays/values.

Path formatting rules

Whitespaces (space, tab character) can be used in bracket notation segments and expressions, for example: $[ 'a' ][ 0 ][ ?( $.b == 'c' ) ][ : -1 ].first( ).

Strings should be enclosed with single (') or double (") quotes. Inside the strings, single or double quotes (depending on which are used to enclose it) and backslashes (\) are escaped with the backslash (\) character.

Example

{
         "books": [
           {
             "category": "reference",
             "author": "Nigel Rees",
             "title": "Sayings of the Century",
             "price": 8.95,
             "id": 1
           },
           {
             "category": "fiction",
             "author": "Evelyn Waugh",
             "title": "Sword of Honour",
             "price": 12.99,
             "id": 2
           },
           {
             "category": "fiction",
             "author": "Herman Melville",
             "title": "Moby Dick",
             "isbn": "0-553-21311-3",
             "price": 8.99,
             "id": 3
           },
           {
             "category": "fiction",
             "author": "J. R. R. Tolkien",
             "title": "The Lord of the Rings",
             "isbn": "0-395-19395-8",
             "price": 22.99,
             "id": 4
           }
         ],
         "services": {
           "delivery": {
             "servicegroup": 1000,
             "description": "Next day delivery in local town",
             "active": true,
             "price": 5
           },
           "bookbinding": {
             "servicegroup": 1001,
             "description": "Printing and assembling book in A5 format",
             "active": true,
             "price": 154.99
           },
           "restoration": {
             "servicegroup": 1002,
             "description": "Various restoration methods",
             "active": false,
             "methods": [
               {
                 "description": "Chemical cleaning",
                 "price": 46
               },
               {
                 "description": "Pressing pages damaged by moisture",
                 "price": 24.5
               },
               {
                 "description": "Rebinding torn book",
                 "price": 99.49
               }
             ]
           }
         },
         "filters": {
           "price": 10,
           "category": "fiction",
           "no filters": "no \"filters\""
         },
         "closed message": "Store is closed",
         "tags": [
           "a",
           "b",
           "c",
           "d",
           "e"
         ]
       }