## JSONPath Concepts

When a state sets the query language to JSONPath, the interpreter supports fields and syntax for querying data using JSONPath paths. For information about JSONata, see JSONata Concepts.

When a state sets the query language to JSONPath, the interpreter supports fields and syntax for querying data using JSONPath paths. For information about JSONata, see JSONata Concepts .

When a state sets the query language to JSONPath, the interpreter supports fields and syntax for querying data using JSONPath paths. For information about JSONata, see JSONata Concepts.

### Paths

A Path is a string, beginning with "$", used to identify components within a JSON text. The syntax is that of JSONPath.

When a Path begins with "$$", two dollar signs, this signals that it is intended to identify content within the Context Object. The first dollar sign is stripped, and the remaining text, which begins with a dollar sign, is interpreted as the JSONPath applying to the Context Object.

### Reference Paths

A Reference Path is a Path with syntax limited in such a way that it can only identify a single node in a JSON structure: the operators "@", ",", ":", and "?" are not supported - all Reference Paths MUST be unambiguous references to a single value, array, or object (subtree).

For example, if state input data contained the values:

    {
      "foo": 123,
      "bar": ["a", "b", "c"],
      "car": {
          "cdr": true
      }
    }

Then the following Reference Paths would return:

    $.foo => 123
    $.bar => ["a", "b", "c"]
    $.car.cdr => true

Paths and Reference Paths are used by certain states, as specified later in this document, to control the flow of a state machine or to configure a state's settings or options.

Here are some examples of acceptable Reference Path syntax:

    $.store.book
    $.store\.book
    $.\stor\e.boo\k
    $.store.book.title
    $.foo.\.bar
    $.foo\@bar.baz\[\[.\?pretty
    $.&Ж中.\uD800\uDF46
    $.ledgers.branch[0].pending.count
    $.ledgers.branch[0]
    $.ledgers[0][22][315].foo
    $['store']['book']
    $['store'][0]['book']

### Payload Template

The interpreter dispatches data as input to tasks to do useful work, and receives output back from them. A common requirement is to reshape input data to meet the format expectations of tasks, and similarly to reshape the output coming back. A JSON object structure called a Payload Template is provided for this purpose.

In the Task, Map, Parallel, and Pass States, the Payload Template is the value of a field named "Parameters". In the Task, Map, and Parallel States, there is another Payload Template which is the value of a field named "ResultSelector".

A Payload Template MUST be a JSON object; it has no required fields. The interpreter processes the Payload Template as described in this section; the result of that processing is called the payload.

To illustrate by example, the Task State has a field named "Parameters" whose value is a Payload Template. Consider the following Task State:

    "X": {
      "Type": "Task",
      "Resource": "arn:aws:states:us-east-1:123456789012:task:X",
      "Next": "Y",
      "Parameters": {
        "first": 88,
        "second": 99
      }
    }

In this case, the payload is the object with "first" and "second" fields whose values are respectively 88 and 99. No processing needs to be performed and the payload is identical to the Payload Template.

Values from the Payload Template’s input and the Context Object can be inserted into the payload with a combination of a field-naming convention, Paths and Intrinsic Functions.

If any field within the Payload Template (however deeply nested) has a name ending with the characters ".$", its value is transformed according to the following rules and the field is renamed to strip the ".$" suffix.

If the field value begins with only one "$", the value MUST be a Path. In this case, the Path is applied to the Payload Template’s input and is the new field value.

If the field value begins with "$$", the first dollar sign is stripped and the remainder MUST be a Path. In this case, the Path is applied to the Context Object and is the new field value.

If the field value does not begin with "$", it MUST be an Intrinsic Function (see Intrinsic Functions). The interpreter invokes the Intrinsic Function and the result is the new field value.

If the path is legal but cannot be applied successfully, the interpreter fails the machine execution with an Error Name of "States.ParameterPathFailure". If the Intrinsic Function fails during evaluation, the interpreter fails the machine execution with an Error Name of "States.IntrinsicFailure".

A JSON object MUST NOT have duplicate field names after fields ending with the characters ".$" are renamed to strip the ".$" suffix.

    "X": {
      "Type": "Task",
      "Resource": "arn:aws:states:us-east-1:123456789012:task:X",
      "Next": "Y",
      "Parameters": {
        "flagged": true,
        "parts": {
          "first.$": "$.vals[0]",
          "last3.$": "$.vals[-3:]"
        },
        "weekday.$": "$$.DayOfWeek",
        "formattedOutput.$": "States.Format('Today is {}', $$.DayOfWeek)"
      }
    }

Suppose that the input to the P is as follows:

    {
      "flagged": 7,
      "vals": [0, 10, 20, 30, 40, 50]
    }

Further, suppose that the Context Object is as follows:

    {
      "DayOfWeek": "TUESDAY"
    }

In this case, the effective input to the code identified in the "Resource" field would be as follows:

    {
      "flagged": true,
      "parts": {
        "first": 0,
        "last3": [30, 40, 50]
      },
      "weekday": "TUESDAY",
      "formattedOutput": "Today is TUESDAY"
    }

### Intrinsic Functions

The States Language provides a small number of "Intrinsic Functions", constructs which look like functions in programming languages and can be used to help Payload Templates process the data going to and from Task Resources. See Appendix B for a full list of Intrinsic Functions

Here is an example of an Intrinsic Function named "States.Format" being used to prepare data:

    "X": {
      "Type": "Task",
      "Resource": "arn:aws:states:us-east-1:123456789012:task:X",
      "Next": "Y",
      "Parameters": {
        "greeting.$": "States.Format('Welcome to {} {}\\'s playlist.', $.firstName, $.lastName)"
      }
    }

1. An Intrinsic Function MUST be a string.

2. The Intrinsic Function MUST begin with an Intrinsic Function name. An Intrinsic Function name MUST contain only the characters A through Z, a through z, 0 through 9, ".", and "_".

   All Intrinsic Functions defined by this specification have names that begin with "States.". The interpreter MAY define its own Intrinsic Functions whose names MUST NOT begin with "States.".

3. The Intrinsic Function name MUST be followed immediately by a list of zero or more arguments, enclosed by "(" and ")", and separated by commas.

4. Intrinsic Function arguments may be strings enclosed by apostrophe (`'`) characters, numbers, null, Paths, or nested Intrinsic Functions.

5. The value of a string, number or null argument is the argument itself. The value of an argument which is a Path is the result of applying it to the input of the Payload Template. The value of an argument which is an Intrinsic Function is the result of the function invocation."

   Note that in the previous example, the first argument of `States.Format` could have been a Path that yielded the formatting template string.

6. The following characters are reserved for all Intrinsic Functions and MUST be escaped: ' { } \

   If any of the reserved characters needs to appear as part of the value without serving as a reserved character, it MUST be escaped with a backslash.

   If the character "\ needs to appear as part of the value without serving as an escape character, it MUST be escaped with a backslash.

   The literal string `\'` represents `'`.
   The literal string `\{` represents `{`.
   The literal string `\}` represents `}`.
   The literal string `\\` represents `\`.

   In JSON, all backslashes contained in a string literal value must be escaped with another backslash, therefore, the preceding sequences will equate to:

   The escaped string `\\'` represents `'`.
   The escaped string `\\{` represents `{`.
   The escaped string `\\}` represents `}`.
   The escaped string `\\\\` represents `\`.

   If an open escape backslash `\` is found in the Intrinsic Function, the interpreter will throw a runtime error.

### Reserved "states" Variable with JSONPath

The States Language reserves one variable called "states". When the query language is JSONPath, its value is defined by the interpreter. This version of the States Language specification does not specify any contents of the "states" variable when the query language is JSONPath. A state MUST NOT assign a value to "states".

### Input and Output Processing with JSONPath

As described earlier, data is passed between states as JSON texts. However, a state may need to process only a subset of its input data, may need to include a portion of one or more variable values, and may need that data structured differently from the way it appears in the input or variables. Similarly, it may need to control the format and content of the data that it passes on as output or that it assigns to variables.

Fields named "InputPath", "Parameters", "ResultSelector", "ResultPath", and "OutputPath" exist to support this.

Any state except for Succeed and Fail MAY have "InputPath" and "OutputPath".

States which potentially generate results MAY have "Parameters", "ResultSelector" and "ResultPath": Task State, Parallel State, and Map State.

Pass State MAY have "Parameters" and "ResultPath" to control its output value.

#### Using InputPath, Parameters, ResultSelector, ResultPath and OutputPath

In this discussion, "raw input" means the JSON text that is the input to a state. "Result" means the JSON text that a state generates, for example from external code invoked by a Task State, the combined result of the branches in a Parallel or Map State, or the Value of the "Result" field in a Pass State. "Effective input" means the input after the application of InputPath and Parameters, "effective result" means the result after processing it with ResultSelector and "effective output" means the final state output after processing the result with ResultSelector, ResultPath and OutputPath.

1. The value of "InputPath" MUST be a Path, which is applied to a State’s raw input to select some or all of it; that selection is used by the state, for example in passing to Resources in Task States and Choices selectors in Choice States.

2. The value of "Parameters" MUST be a Payload Template which is a JSON object, whose input is the result of applying the InputPath to the raw input. If the "Parameters" field is provided, its payload, after the extraction and embedding, becomes the effective input.

3. The value of "ResultSelector" MUST be a Payload Template, whose input is the result, and whose payload replaces and becomes the effective result.

4. The value of "ResultPath" MUST be a Reference Path, which specifies the raw input’s combination with or replacement by the state’s result.

   The value of "ResultPath" MUST NOT begin with "$$"; i.e. it may not be used to insert content into the Context Object.

5. The value of "OutputPath" MUST be a Path, which is applied to the state’s output after the application of ResultPath, producing the effective output which serves as the raw input for the next state.

Note that JSONPath can yield multiple values when applied to an input JSON text. For example, given the text:

    { "a": [1, 2, 3, 4] }

Then if the JSONPath `$.a[0,1]` is applied, the result will be two JSON texts, `1` and `2`. When this happens, to produce the effective input, the interpreter gathers the texts into an array, so in this example the state would see the input:

    [ 1, 2 ]

The same rule applies to OutputPath processing; if the OutputPath result contains multiple values, the effective output is a JSON array containing all of them.

The "ResultPath" field’s value is a Reference Path that specifies where to place the result, relative to the raw input. If the raw input has a field at the location addressed by the ResultPath value then in the output that field is discarded and overwritten by the state's result. Otherwise, a new field is created in the state output, with intervening fields constructed as necessary. For example, given the raw input:

    {
      "master": {
        "detail": [1, 2, 3]
      }
    }

    {
      "master": {
        "detail": [1, 2, 3]
      }
    }

    {
      "master": {
        "detail": [1, 2, 3]
      }
    }

If the state's result is the number `6`, and the "ResultPath" is `$.master.detail`, then in the output the `detail` field would be overwritten:

    {
      "master": {
        "detail": 6
      }
    }

If instead a "ResultPath" of `$.master.result.sum` was used then the result would be combined with the raw input, producing a chain of new fields containing `result` and `sum`:

    {
      "master": {
        "detail": [1, 2, 3],
        "result": {
          "sum": 6
        }
      }
    }

If the value of InputPath is `null`, that means that the raw input is discarded, and the effective input for the state is an empty JSON object, `{}`. Note that having a value of `null` is different from the "InputPath" field being absent.

If the value of ResultPath is `null`, that means that the state’s result is discarded and its raw input becomes its result.

If the value of OutputPath is `null`, that means the input and result are discarded, and the effective output from the state is an empty JSON object, `{}`.

#### Using Assign

The value of "$" in "Assign" depends on the state type. In Task, Map, and Parallel States, "$" refers to the result in a state's top-level "Assign", and to the Error Output in a Catcher's "Assign". In Choice and Wait States, "$" refers to the effective input, which is the value after "InputPath" has been applied to the state input. For Pass State, "$" refers to the result, whether generated by the "Result" field or the "InputPath" and "Parameters" fields.

#### Defaults

Each of InputPath, Parameters, ResultSelector, ResultPath, and OutputPath are optional. The default value of InputPath is "$", so by default the effective input is just the raw input. The default value of ResultPath is "$", so by default a state’s result overwrites and replaces the input. The default value of OutputPath is "$", so by default a state’s effective output is the result of processing ResultPath.

Parameters and ResultSelector have no default value. If absent, they have no effect on their input.

Therefore, if none of InputPath, Parameters, ResultSelector, ResultPath, or OutputPath are supplied, a state consumes the raw input as provided and passes its result to the next state.

#### Input/Output Processing Examples

Consider the previous example of a Lambda task that sums a pair of numbers. As presented, its input is: `{ "val1": 3, "val2": 4 }` and its output is: `7`.

Suppose the input is little more complex:

    {
      "title": "Numbers to add",
      "numbers": { "val1": 3, "val2": 4 }
    }

Then suppose we modify the state definition by adding:

    "InputPath": "$.numbers",
    "ResultPath": "$.sum"

And finally, suppose we simplify Line 4 of the Lambda function to read as follows: `return JSON.stringify(total)`. This is probably a better form of the function, which should really only care about doing math and not care how its result is labeled.

In this case, the output would be:

    {
      "title": "Numbers to add",
      "numbers": { "val1": 3, "val2": 4 },
      "sum": 7
    }

The interpreter might need to construct multiple levels of JSON object to achieve the desired effect. Suppose the input to some Task State is:

    { "a": 1 }

Suppose the output from the Task is "Hi!", and the value of the "ResultPath" field is "$.b.greeting". Then the output from the state would be:

    {
      "a": 1,
      "b": {
        "greeting": "Hi!"
      }
    }

#### JSONPath Runtime Errors

Suppose a state’s input is the string `"foo"`, and its "ResultPath" field has the value "$.x". Then ResultPath cannot apply and the interpreter fails the machine with an Error Name of "States.ResultPathMatchFailure".

## Appendices

### Appendix A: Predefined Error Codes

Code | Description
--- | ---
States.ALL | A wildcard which matches any Error Name.
States.HeartbeatTimeout | A Task State failed to heartbeat for a time longer than the "HeartbeatSeconds" value.
States.Timeout | A Task State either ran longer than the "TimeoutSeconds" value, or failed to heartbeat for a time longer than the "HeartbeatSeconds" value.
States.TaskFailed | A Task State failed during the execution.
States.Permissions | A Task State failed because it had insufficient privileges to execute the specified code.
States.ResultPathMatchFailure | A state’s "ResultPath" field cannot be applied to the input the state received.
States.ParameterPathFailure | Within a state’s "Parameters" field, the attempt to replace a field whose name ends in ".$" using a Path failed.
States.QueryEvaluationError | Query evaluation failed in a JSONata state, such as a JSONata type error, an incorrectly typed result, or an undefined result.
States.BranchFailed | A branch of a Parallel State failed.
States.NoChoiceMatched | A Choice State failed to find a match for the condition field extracted from its input.
States.IntrinsicFailure | Within a Payload Template, the attempt to invoke an Intrinsic Function failed.
States.ExceedToleratedFailureThreshold | A Map state failed because the number of failed items exceeded the configured tolerated failure threshold.
States.ItemReaderFailed | A Map state failed to read all items as specified by the "ItemReader" field.
States.ResultWriterFailed | A Map state failed to write all results as specified by the "ResultWriter" field.

### Appendix B: List of JSONPath Intrinsic Functions

The States Language provides a set of intrinsic functions that provide additional functionality for JSONPath. Intrinsic functions MAY be used in states that use the JSONPath query language, and MUST NOT be used in states that use any other query language.

#### States.Format

This Intrinsic Function takes one or more arguments. The Value of the first MUST be a string, which MAY include zero or more instances of the character sequence `{}`. There MUST be as many remaining arguments in the Intrinsic Function as there are occurrences of `{}`. The interpreter returns the first-argument string with each `{}` replaced by the Value of the positionally-corresponding argument in the Intrinsic Function.

If necessary, the `{` and `}` characters can be escaped respectively as `\\{` and `\\}`.

If the argument is a Path, applying it to the input MUST yield a value that is a string, a boolean, a number, or `null`. In each case, the Value is the natural string representation; string values are not accompanied by enclosing `"` characters. The Value MUST NOT be a JSON array or object.

For example, given the following Payload Template:

    {
      "Parameters": {
        "foo.$": "States.Format('Your name is {}, we are in the year {}', $.name, 2020)"
      }
    }

Suppose the input to the Payload Template is as follows:

    {
      "name": "Foo",
      "zebra": "stripe"
    }

After processing the Payload Template, the new payload becomes:

    {
      "foo": "Your name is Foo, we are in the year 2020"
    }

#### States.StringToJson

This Intrinsic Function takes a single argument whose Value MUST be a string. The interpreter applies a JSON parser to the Value and returns its parsed JSON form.

For example, given the following Payload Template:

    {
      "Parameters": {
        "foo.$": "States.StringToJson($.someString)"
      }
    }

Suppose the input to the Payload Template is as follows:

    {
      "someString": "{\"number\": 20}",
      "zebra": "stripe"
    }

After processing the Payload Template, the new payload becomes:

    {
      "foo": {
        "number": 20
      }
    }

#### States.JsonToString

This Intrinsic Function takes a single argument which MUST be a Path. The interpreter returns a string which is a JSON text representing the data identified by the Path.

For example, given the following Payload Template:

    {
      "Parameters": {
        "foo.$": "States.JsonToString($.someJson)"
      }
    }

Suppose the input to the Payload Template is as follows:

    {
      "someJson": {
        "name": "Foo",
        "year": 2020
      },
      "zebra": "stripe"
    }

After processing the Payload Template, the new payload becomes:

    {
      "foo": "{\"name\":\"Foo\",\"year\":2020}"
    }

#### States.Array

This Intrinsic Function takes zero or more arguments. The interpreter returns a JSON array containing the Values of the arguments, in the order provided.

For example, given the following Payload Template:

    {
      "Parameters": {
        "foo.$": "States.Array('Foo', 2020, $.someJson, null)"
      }
    }

Suppose the input to the Payload Template is as follows:

    {
      "someJson": {
        "random": "abcdefg"
      },
      "zebra": "stripe"
    }

After processing the Payload Template, the new payload becomes:

    {
      "foo": [
        "Foo",
        2020,
        {
          "random": "abcdefg"
        },
        null
      ]
    }

#### States.ArrayPartition

Use the `States.ArrayPartition` intrinsic function to partition a large array or to slice the data and then send the payload in smaller chunks.

This intrinsic function takes two arguments. The first argument is an array, while the second argument defines the chunk size. The interpreter chunks the input array into multiple arrays of the size specified by chunk size. The length of the last array chunk may be less than the length of the previous array chunks if the number of remaining items in the array is smaller than the chunk size.

Input validation

- The first argument MUST be an array.

- The second argument MUST be a non-zero, positive integer, representing the chunk size value.

For example, given the following input array:

    { "inputArray": [1,2,3,4,5,6,7,8,9] }

Use the `States.ArrayPartition` function to divide the array into chunks of four values:

    { "inputArray.$": "States.ArrayPartition($.inputArray,4)" }

Which would return the following array chunks:

    { "inputArray": [ [1,2,3,4], [5,6,7,8], [9]] }

In the previous example, the `States.ArrayPartition` function outputs three arrays. The first two arrays each contain four values, as defined by the chunk size. A third array contains the remaining value and is smaller than the defined chunk size.

#### States.ArrayContains

Use the `States.ArrayContains` intrinsic function to determine if a specific value is present in an array. For example, use this function to detect if there was an error in a `Map` state iteration.

This intrinsic function takes two arguments. The first argument is an array, while the second argument is the value to be searched for within the array.

Input validation

- The first argument MUST be an array
- The second argument MUST be a JSON object

For example, given the following input array:

    { "inputArray": [1,2,3,4,5,6,7,8,9], "lookingFor": 5 }

Use the `States.ArrayContains` function to find the `lookingFor` value within the `inputArray`:

    { "contains.$": "States.ArrayContains($.inputArray, $.lookingFor)" }

Because the value stored in `lookingFor` is included in the `inputArray`, `States.ArrayContains` returns the following result:

    { "contains": true }

#### States.ArrayRange

Use the `States.ArrayRange` intrinsic function to create a new array containing a specific range of elements. The new array can contain up to 1000 elements.

This function takes three arguments. The first argument is the first element of the new array, the second argument is the final element of the new array, and the third argument is the increment value between the elements in the new array.

Input validation

- All arguments MUST be integer values.

- The third argument MUST NOT be zero.

- The newly generated array MUST NOT contain more than 1000 items.

For example, the following use of the `States.ArrayRange` function will create an array with a first value of 1, a final value of 9, and values in between the first and final values increase by two for each item:

    { "array.$": "States.ArrayRange(1, 9, 2)" }

Which would return the following array:

    { "array": [1,3,5,7,9] }

#### States.ArrayGetItem

This intrinsic function returns a specified index's value. This function takes two arguments. The first argument is an array of values and the second argument is the array index of the value to return.

For example, use the following `inputArray` and `index` values:

    { "inputArray": [1,2,3,4,5,6,7,8,9], "index": 5 }

Use the `States.ArrayGetItem` function to return the value in the `index` position 5 within the array:

    { "item.$": "States.ArrayGetItem($.inputArray, $.index)" }

In this example, `States.ArrayGetItem` would return the following result:

    { "item": 6 }

#### States.ArrayLength

The `States.ArrayLength` intrinsic function returns the length of an array. It has one argument, the array to return the length of.

For example, given the following input array:

    { "inputArray": [1,2,3,4,5,6,7,8,9] }

Use `States.ArrayLength` to return the length of `inputArray`:

    { "length.$": "States.ArrayLength($.inputArray)" }

In this example, `States.ArrayLength` would return the following JSON object that represents the array length:

    { "length": 9 }

#### States.ArrayUnique

The `States.ArrayUnique` intrinsic function removes duplicate values from an array and returns an array containing only unique elements. This function takes an array, which can be unsorted, as its sole argument.

For example, the following `inputArray` contains a series of duplicate values:

    { "inputArray": [1,2,3,3,3,3,3,3,4] }

The `States.ArrayUnique` function can be used to remove duplicate values from the array:

    { "array.$": "States.ArrayUnique($.inputArray)" }

The `States.ArrayUnique` function would return the following array containing only unique elements, removing all duplicate values:

    { "array": [1,2,3,4] }

#### States.Base64Encode

Use the `States.Base64Encode` intrinsic function to encode data based on MIME Base64 encoding scheme. For example, use this function to pass data to other AWS services without using an AWS Lambda function.

This function takes a data string of up to 10,000 characters to encode as its only argument.

For example, consider the following `input` string:

    { "input": "Data to encode" }

Use the `States.Base64Encode` function to encode the `input` string as a MIME Base64 string:

    { "base64.$": "States.Base64Encode($.input)" }

The `States.Base64Encode` function returns the following encoded data in response:

    { "base64": "RGF0YSB0byBlbmNvZGU=" }

#### States.Base64Decode

Use the `States.Base64Decode` intrinsic function to decode data based on MIME Base64 decoding scheme. For example, use this function to pass data to other AWS services without using a Lambda function.

This function takes a Base64 encoded data string of up to 10,000 characters to decode as its only argument.

For example, given the following input:

    { "base64": "RGF0YSB0byBlbmNvZGU=" }

Use the `States.Base64Decode` function to decode the base64 string to a human-readable string:

    { "data.$": "States.Base64Decode($.base64)" }

The `States.Base64Decode function` would return the following decoded data in response:

    { "data": "Decoded data" }

#### States.Hash

Use the `States.Hash` intrinsic function to calculate the hash value of a given input. For example, use this function to pass data to other AWS services without using a Lambda function.

This function takes two arguments. The first argument is the data to hash. The length of the stringified version of the first argument must be 10,000 characters or less. The second argument is the hashing algorithm to use to perform the hash calculation.

The hashing algorithm can be any of the following algorithms:

- MD5
- SHA-1
- SHA-256
- SHA-384
- SHA-512

For example, given the `Data` string and a specific `Algorithm`:

    { "Data": "input data", "Algorithm": "SHA-1" }

Use the `States.Hash` function to calculate the hash value:

    { "output.$": "States.Hash($.Data, $.Algorithm)" }

The `States.Hash` function returns the following hash value in response:

    { "output": "aaff4a450a104cd177d28d18d7485e8cae074b7" }

#### States.JsonMerge

Use the `States.JsonMerge` intrinsic function to merge two JSON objects into a single object. This function takes three arguments. The first two arguments are the JSON objects to merge. The third argument is a boolean value that is `false` to do a shallow merge, and `true` to do a deep merge.

In shallow mode, if the same field name exists in both JSON objects, the latter object's field overrides the field with the same name in the first object.

In deep mode, if the same field name exists in both JSON objects, and both fields are themselves JSON objects, the function merges them. Deep mode repeats this process recursively.

For example, use the `States.JsonMerge` function to merge the following JSON arrays that both have a field named `a`.

    {
      "json1": { "a": {"a1": 1, "a2": 2}, "b": 2, },
      "json2": { "a": {"a3": 1, "a4": 2}, "c": 3 }
    }

Specify the `json1` and `json2` arrays as inputs in the `States.JasonMerge` function to merge them together:

    { "output.$": "States.JsonMerge($.json1, $.json2, false)" }

The `States.JsonMerge` returns the following merged JSON object as result. In the merged JSON object `output`, the `json2` object's field `a` replaces the `json1` object's field `a`. Also, the nested object in `json1` object's field `a` is discarded because shallow mode does not support merging nested objects.

    { "output": { "a": {"a3": 1, "a4": 2}, "b": 2, "c": 3 } }

#### States.MathRandom

Use the `States.MathRandom` intrinsic function to return a random number between the specified start and end number. For example, use this function to distribute a specific task between two or more resources.

This function takes three arguments. The first argument is the start number, the second argument is the end number, and the last argument controls the seed value. The seed value argument is optional.

Each use of this function with the same seed value will produce the same result.

Important

Because the `States.MathRandom` function does not return cryptographically secure random numbers, we recommend not to use it for security sensitive applications.

Input validation

- The start number and end number MUST be integers.

For example, to generate a random number from between one and 999, use the following input values:

    { "start": 1, "end": 999 }

To generate the random number, provide the `start` and `end` values to the `States.MathRandom` function:

    { "random.$": "States.MathRandom($.start, $.end)" }

The `States.MathRandom` function returns the following random number as a response:

    { "random": 456 }

#### States.MathAdd

Use the `States.MathAdd` intrinsic function to return the sum of two numbers. For example, use this function to increment values inside a loop without invoking a Lambda function.

Input validation

- All arguments MUST be integers.

For example, use the following values to subtract one from 111:

    { "value1": 111, "step": -1 }

Then, use the `States.MathAdd` function defining `value1` as the starting value, and `step` as the value to increment `value1` by:

    { "value1.$": "States.MathAdd($.value1, $.step)" }

The `States.MathAdd` function would return the following number in response:

    { "value1": 110 }

#### States.StringSplit

Use the `States.StringSplit` intrinsic function to split a string into an array of values. This function takes two arguments. The first argument is a string and the second argument is the delimiting character that the function will use to divide the string.

For example, use `States.StringSplit` to divide the following `inputString`, which contains a series of comma separated values:

    { "inputString": "1,2,3,4,5", "splitter": "," }

Use the `States.StringSplit` function and define `inputString` as the first argument, and the delimiting character `splitter` as the second argument:

    { "array.$": "States.StringSplit($.inputString, $.splitter)" }

The `States.StringSplit` function returns the following string array as result:

    { "array": ["1","2","3","4","5"] }

#### States.UUID

Use the `States.UUID` intrinsic function to return a version 4 universally unique identifier (v4 UUID) generated using random numbers. For example, use this function to call other AWS services or resources that need a UUID parameter or insert items in a DynamoDB table.

The `States.UUID` function is called with no arguments specified:

    { "uuid.$": "States.UUID()" }

The function returns a randomly generated UUID, for example:

    { "uuid": "ca4c1140-dcc1-40cd-ad05-7b4aa23df4a8" }