Articles in this section

JSONPath notation

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

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