A JSONPath expression specifies a path to an element (or a set of elements) in a JSON structure . Learning this skill is essential to mapping fields with Mapper 2.0 and/or transforming source records with Transformation 2.0.
|
Operators |
|
|---|---|
To test JSONPath notation syntax, visit JSONPath.com.
Signifies the root object or array element.
|
Expression |
Context |
Output |
|---|---|---|
$.items |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
}
]
}
|
[
[
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
}
]
]
|
Use child operators to reference paths with either dot notation, bracket notation, or a mix of both. Use bracket notation with single or double quotes if the property name contains special characters or spaces.
|
Expression |
Context |
Output |
|---|---|---|
$.items[0].description or $["items"][0]["description"] or $["items"][0].description |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
}
]
}
|
[ "Hat" ] |
The recursive descent operator returns an array of all values for the specified field nested one level below the current JSON hierarchy. The following example returns all "description" values for any instance nested one level deeper in the record.
|
Expression |
Context |
Output |
|---|---|---|
$..description |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
}
]
}
|
[ "Hat", "Shoes" ] |
Select multiple values in an array by referencing each position separated by a comma. the following example selects the first and third objects from the "items" array.
|
Expression |
Context |
Output |
|---|---|---|
items.[0,2] |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
},
{
"description": "shirt",
"qty": 1
}
]
}
|
[
{
"description": "Hat",
"qty": 3
},
{
"description": "shirt",
"qty": 1
}
]
|
The n-th position in an array starting from index position zero. In the following example, the first object in the "items" array is selected at position zero.
|
Expression |
Context |
Output |
|---|---|---|
$.items.[0] |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
}
]
}
|
[
{
"description": "Hat",
"qty": 3
}
]
|
The reverse n-th index position of the array. A negative n-th position in an array counts the value backward from the last item of the array. The following example selects the last item in the array.
|
Expression |
Context |
Output |
|---|---|---|
$.items.[-1:] |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
},
{
"description": "shirt",
"qty": 1
},
{
"description": "pants",
"qty": 1
},
{
"description": "glasses",
"qty": 1
}
]
}
|
[
{
"description": "glasses",
"qty": 1
}
]
|
The wildcard asterisk selects all elements in an object or an array, regardless of name or index in an array. The following example returns all objects in the "items" array.
|
Expression |
Context |
Output |
|---|---|---|
$.items.* |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
}
]
}
|
[
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
}
]
|
Selects items in an array from start position up to (but not including) end position. The following example returns the items array from position 1 to position 3. Notice that value referenced for the end position (4) is not included in the results.
|
Expression |
Context |
Output |
|---|---|---|
$.items.[1:4] |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
},
{
"description": "shirt",
"qty": 1
},
{
"description": "pants",
"qty": 1
},
{
"description": "glasses",
"qty": 1
}
]
}
|
[
{
"description": "Shoes",
"qty": 1
},
{
"description": "shirt",
"qty": 1
},
{
"description": "pants",
"qty": 1
}
]
|
If an end value is not provided, all items after the specified start position return. The start position value returns in the output.
|
Expression |
Context |
Output |
|---|---|---|
$.items.[1:] |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
},
{
"description": "shirt",
"qty": 1
},
{
"description": "pants",
"qty": 1
},
{
"description": "glasses",
"qty": 1
}
]
}
|
[
{
"description": "Shoes",
"qty": 1
},
{
"description": "shirt",
"qty": 1
},
{
"description": "pants",
"qty": 1
},
{
"description": "glasses",
"qty": 1
}
]
|
Position zero of the array is assumed if the start position value is not provided, all items before the end position of the array return. The end position item of the array does not return in the output.
|
Expression |
Context |
Output |
|---|---|---|
$.items.[:2] |
{
"orderId": 123,
"total": 99.99,
"state": "ca",
"items": [
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
},
{
"description": "shirt",
"qty": 1
},
{
"description": "pants",
"qty": 1
},
{
"description": "glasses",
"qty": 1
}
]
}
|
[
{
"description": "Hat",
"qty": 3
},
{
"description": "Shoes",
"qty": 1
}
]
|