Motivation

The AWS Step Functions API and Amazon States Language (ASL) have newly introduced support for the following features:

• The JSONata query and transformation language as an alternative to JSONPath.
• Workflow variables that allow the ability to assign and reference variables in ASL.

Changes

JSONata

• Step Function definitions can now use a QueryLanguage field to specify whether to evaluate expressions using JSONata or JSONPath (default). This can be set at the:
  • Top-level, setting the entire state machine's query language.
  • State-level, setting the current state's query language.
• Strings values surrounded by {% %} will be evaluated as JSONata where present as the value of a non-Path ASL field, a JSON object field, or a JSON array element.
• The Arguments and Output fields replace usage of the input and output Path fields in JSONPath (InputPath, Parameters, ResultSelector, ResultPath, and OutputPath).
• Path versions of fields are not supported, where JSONata enclosed expressions should be used instead.
• Step Functions will reserve a read-only JSONata variable called $states with the following values:
  • $states.input: A state's raw input
  • $states.result: An API or sub-workflow's result (if successful)
  • $states.errorOutput: An error output (only available in Catch)
  • $states.context: The context object
• The Map state Items field has been added that accepts a JSON array or a JSONata expression that must evaluate to an array.
• The Choice state Condition field for choice rules that accepts a boolean constant or a JSONata expression that must evaluate to a boolean.
• Step Functions provides access to the built-in JSONata function library can be used when defining expressions. This replaces the usage of Step Functions' intrinsic functions.

Worfklow Variables

• Variables can be assigned in JSONata or JSONPath states using the new Assign field.
• Once assigned, workflow variables can be referenced anywhere (with some exceptions due to scoping and the order of evaluation) using the $ prefix. For example, an assigned variable foo can be accessed with a $ like $foo.
  • A JSONata reference will require the {% %} to enclose the statement i.e

    "Seconds": "{% $foo %}",
    

  • A JSONPath reference will require the ASL field to include a .$ suffix to follow the field name i.e

    "SecondsPath.$": "$foo",
    

    However, this is not required for InputPath, ResultSelector, ResultPath, and OutputPath.