Paths - AWS Step Functions
Reference Paths

Paths

In the Amazon States Language, a path is a string beginning with $ that you can use to identify components within JSON text. Paths follow JsonPath syntax. You can specify a path to access subsets of the input when specifying values for InputPath, ResultPath, and OutputPath. For more information see Input and Output Processing in Step Functions.

Note

You can also specify a JSON node of the input or the context object by using paths within the Parameters field of a state definition. See Pass parameters to a service API.

You must use square bracket notation if your field name contains any character that is not included in the member-name-shorthand definition of the JsonPath ABNF rule. Therefore, to encode special characters, such as punctuation marks (excluding _), you must use square bracket notation. For example, $.abc.['def ghi'].

Reference Paths

A reference path is a path whose syntax is limited in such a way that it can identify only a single node in a JSON structure:

  • You can access object fields using only dot (.) and square bracket ([ ]) notation.

  • Functions such as length() aren't supported.

  • Lexical operators, which are non-symbolic, such as subsetof aren't supported.

  • Filtering by regular expression or by referencing another value in the JSON structure isn't supported.

  • The @ operator, matching the current node being processed in a filter, does not match scalar values. It only matches objects.

For example, if state input data contains the following values:

{
  "foo": 123,
  "bar": ["a", "b", "c"],
  "car": {
      "cdr": true
  },
  "jar": [{"a": 1}, {"a": 5}, {"a": 2}, {"a": 7}, {"a": 3}]
}

The following reference paths would return the following.

$.foo => 123
$.bar => ["a", "b", "c"]
$.car.cdr => true
$.jar[?(@.a >= 5)] => [{"a": 5}, {"a": 7}]

Certain states use paths and reference paths to control the flow of a state machine or configure a state's settings or options. For more information, see Modeling workflow input and output path processing with data flow simulator and Using JSONPath effectively in AWS Step Functions.

Flattening an array of arrays

If the Parallel or Map state in your state machines return an array of arrays, you can transform them into a flat array with the ResultSelector field. You can include this field inside the Parallel or Map state definition to manipulate the result of these states.

To flatten arrays, use the JMESPath syntax [*] in the ResultSelector field as shown in the following example.

"ResultSelector": {
    "flattenArray.$": "$[*][*]"
  }

For examples that show how to flatten an array, see Step 3 in the following tutorials: