Skip to main content

JSONPath notation

Tom Santiago
  • Updated

A JSONPath expression specifies a path to an element (or a set of elements) in a JSON structure. Only Mapper 2.0 supports JSONPath notation. Learning this skill is essential to mapping fields with Mapper 2.0.

JSONPath reference operators

Operators
$ (root)

* (wildcard)

. or []

[n]

..fieldName

 [start:end]

[-n:]

 [?(@.fieldName)]

[,]

  

To test JSONPath notation syntax, visit JSONPath.com.

$

Signifies the root object or array element. This JSONPath element can be omitted because the syntax assumes root as the default starting place for an expression.

Expression Context Output 
$.items

or

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

[?(@.fieldName)]

Filters all items in an array that contain a specified field. The following example selects all items in the array that have a field named "color".

Expression Context Output 
$..items[?(@.color)]
 
{
  "orderId": 123,
  "total": 99.99,
  "state": "ca",
  "items": [
    {
      "description": "Hat",
      "color": "black",
      "qty": 3
    },
    {
      "description": "Shoes",
      "qty": 1
    },
    {
      "description": "shirt",
      "qty": 1
    },
    {
      "description": "pants",
      "color": "blue",
      "qty": 1
    },
    {
      "description": "glasses",
      "qty": 1
    }
  ]
}
 
[
  {
    "description": "Hat",
    "color": "black",
    "qty": 3
  },
  {
    "description": "pants",
    "color": "blue",
    "qty": 1
  }
]

You can also include basic evaluations for filters. The following example selects all items that have a qty value that is greater than 1.

Expression Context Output 
$..items[?(@.qty>1)]
 
{
  "orderId": 123,
  "total": 99.99,
  "state": "ca",
  "items": [
    {
      "description": "Hat",
      "color": "black",
      "qty": 3
    },
    {
      "description": "Shoes",
      "qty": 1
    },
    {
      "description": "shirt",
      "qty": 1
    },
    {
      "description": "pants",
      "color": "blue",
      "qty": 1
    },
    {
      "description": "glasses",
      "qty": 1
    }
  ]
}
 
[
  {
    "description": "Hat",
    "color": "black",
    "qty": 3
  }
]

Related articles

Comments

0 comments

Please sign in to leave a comment.