JSONPath

This chapter describes JSONPath only within GudHub. Accordingly, it contains partial information about that.

JSONPath is a query language for JSON with features that allows to get required data from JSON. It is used for selecting and extracting a sub-section from the JSON document. JSONPath expressions, including property names and values, are case-sensitive.

JsonPath expressions always refer to a JSON structure in the same way as XPath expressions are used in combination with an XML document. It has several special rules for writing:

Every query starts from $ character:

  $.app_id.item_id
  $..item_id
  $[app_id].item_id

JSONPath expressions can use the dot notation, the bracket notation or a mix of dot and bracket notations:
```
  $.store.book[0].title

  $['store']['book'][0]['title']

  $['store'].book[0].title
```
Dots are only used before property names not in brackets.
Within JSONPath expressions, text values are enclose in double quotes.

Other syntax elements are described in following table.

Name	Description
`$`	represents the root object or array and can be omitted
`.property`	selects the specified property in a parent object
`['property']`	selects the specified property in a parent object; is used for property names with special characters
`[n]`	allows to select the n-th element from the array
`[index1,index2,…]`	allows to select an array of elements with the specifies indexes
`..property`	recursively searches for property name and returns array of all values with it
`*`	wildcard selects all elements in an object or an array, regardless of their names or indexes
`[start:end]`	selects elements from the start index to the end one
`[:n]`	selects the first elements of the array
`[-n:]`	selects the last elements of the array
`[?(expression)]`	filter expression
`[(expression)]`	allows to use script expressions instead of explicit property names or indexes
`@`	used in filter expressions to refer to the current node being processed

JSONPath queries can return a single element and a list of matching elements. For example, we have JSON:

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

Enter JSON expressions:

$.phoneNumbers[0].type
$.phoneNumbers[*].number

As the result we will get:

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

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

Filter

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

Filter operators

Operators that can be used for filters in GudHub:

№	Operator	Priority	Description
1.	==	1	shows fields whose value are equal to the one in filter
2.	!=	1	shows fields whose value are not equal to the one in filter
3.	&&	2	logical AND, used to combine multiple filter expressions
4.	\| \|	2	logical OR, used to combine multiple filter expressions

Following is a table of relevant examples:

№	Operator	Example expression
1.	==	`[?(@.color == 'red')]`
2.	!=	`[?(@.color != 'red')]`
3.	&&	`[?(@.color=='red' && @.number < 12)]`
4.	\| \|	`[?(@.color=='red' \\|\\| @.number < 12)]`

You can find examples of using filters in jsonToItems tutorial.