Articles in this section

JSONPath notation

Tom Santiago
Updated

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.

JSONPath reference operators

Operators
$ (root)

[,]

. or []

* (wildcard)

..fieldName

 [n]

[-n:]

 [start:end]

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
    }
  ]
]

. or []

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

..fieldName

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
  }
]

[n]

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
  }
]

[-n:]

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
  }
]

[start:end]

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
  }
]

 

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.