In this Page

A JSONPath expression lets you specify the parts of a JSON document that are to be operated on by a Snap. For example, to reference the "name" field at the root of a document, you can use the path "$.name". More complex paths are also possible that will let you walk an entire document looking for a particular field, filter objects based on their value, and so on. If you are familiar with XPath for XML documents, than JSONPath is a similar concept for JSON documents.

Supported Snaps

The following Snaps use JSONPath:

Structure - The Structure Snap allows you to reshape a document, moving values, deleting fields, and so on.
Mapper (Data) - The Mapper (Data) Snap evaluates an expression and writes the result to the destinations given by the target JSONPath. Be aware that the expression language syntax and JSONPath syntax are not compatible. Simple syntax like "$.name" is valid in both, but anything non-trivial will likely not work.

Syntax

The basic syntax supported by the Snaps follows the original JSONPath specification. The following is a summary of the syntax.

Syntax	Example Path	Result	Description
$	$		The document root.
. (dot)	$.parent.child	The 'child' field from the 'parent' object.	Child operator. This operator is used to select a field in a parent object.
[]	$.parent['child with spaces']	The 'child with spaces' field from the 'parent' object.	Child operator or array index. This operator can used to select a field that may contain special characters that need to be quoted.
	$.children[1]	The second element of the 'child' array.
	$.children[-1]	The last element in the array.
*	$.children[*].age	The 'age' values from the elements of the 'children' array.	Wildcard operator. Selects all elements in an array or an object.
..	$..child	All of 'child' fields found in the document.	The descent operator. Traverses the entire document searching for the fields and elements that match the rest of the path.
[start:end:step]	$.children[1:]	All but the first element of the 'children' array.	The array slice operator. The 'start' value specifies the starting index for the slice. If not specified, then zero is used for the start. The 'end' value specifies the exclusive end of the slice. If no end is given, then the end of the list is used. The 'step' value specifies how many elements the operator moves through at a time. If no step is given, then one is used. If the 'start' or 'end' values fall outside of the bounds of the array, they will automatically be adjusted to the nearest bounds and not trigger an error.
	$.children[::2]	Every other element in the 'children' array.
	$.children[::-1]	All elements of the 'children' array in reverse order.
[,]	$.parent['child1','child2']	The fields of the 'parent' object named 'child1' and 'child2'.	The union operator. Selects the array elements or object fields with the given indexes or names, respectively.
?(expr)	$.children[?(value.age > 18)]	Only those elements in the 'children' array where the 'age' field is greater than 18.	The filter operator. Selects all elements in an array or an object that match the given expression. In the expression, the 'value' variable refers to the array element or object value and the 'key' variable refers to the field name in the object.
(expr)	$.parent[(_name)]	The field from the 'parent' object that is specified by the 'name' pipeline parameter.	The expression operator. Select the array element or object field as specified by the enclosed expression.
{defaultValue:<value>}	($, '$.store.book.author*', {defaultValue: Anonymous} )	When the book author is not found, the author is listed as Anonymous.	Sets a default value for JSONPath. If a specified path exists, it's value is returned. If any part of the path is missing, then the default value is returned.

Extended Syntax

When using JSONPath to query a document, the basic syntax can cover the majority of use-cases, however, there are often times when you wish to process the results of a query. For example, if an array contained a list of addresses (e.g. home, work), you could use a filter to select the home address (i.e. $.addresses[?(value.type == 'home')]), but the result is still in a list. So, rather than require an extra Snap to extract the address object from a list, we have extended the standard JSONPath syntax with some method calls that can be used to manipulate the results of a query.

Syntax	Example Path	Result	Description
.map(expr)	$.children.map(value.age )	An array of all the 'age' fields from the objects in the 'children' array.	Iterate over the elements of an array, execute the given expression for each element, and return an array with the results. The 'value' variable will be set to the value of the current element.
	$.children.map({ name: value.fname + " " + value.lname, age: value.age })	An array of all the children objects that has been remapped so that there is only a single 'name' field instead of 'fname' and 'lname'.
.eval(expr)	$.children[?(value.age > 18)].eval(value[0])	The first child whose age is greater than 18.	Evaluate an expression on the result of the path. The 'value' variable is set to the result of the query.
	$.eval(_pipe_param)	The value of the 'pipe_param' pipeline parameter. Note that we do not actually use the result of the path here.
.sort_asc(expr)	$.children.sort_asc(value.age)	The children array sorted from lowest age to highest.	Sort an array in ascending order based on the given expression.
.sort_desc(expr)	$.children.sort_desc(value.age)	The children array sorted from highest age to lowest.	Sort an array in descending order based on the given expression.
.group_by(expr)	$.children.group_by(value.gender)	An object with fields for each gender found in the 'children' array. Each field will then contain a list of objects that have that gender value. For example, if there were two boys and one girl in the children list, the object would contain a 'male' field that had a list of the two boys and a 'female' field with a list containing the one girl.	Group the values in an array based on the result of a given expression. The result will be an object with fields for each expression result and a list of the objects that matched that value.

Object Example

If your JSON for an object looks like this:

{
  "user":
  {
"id": 279,
"screenName": "mynameonline",
"full name": "Joe User"
}
    }

your path examples could look like this:

$user.screenName
$user.['full name']

Array Example