/aws-step-functions

Migrating from JSONPath to JSONata

Complete conversion guide for migrating existing JSONPath state machines to JSONata. Covers fields, states, intrinsic functions, common pitfalls, and the end-to-end conversion workflow.

JSONPath → JSONata Quick Reference

Converting Each State Type

Task State

Before (JSONPath):

"ProcessOrder": {
  "Type": "Task",
  "Resource": "arn:aws:states:::lambda:invoke",
  "InputPath": "$.order",
  "Parameters": {
    "FunctionName": "arn:aws:lambda:us-east-1:123456789012:function:Process:$LATEST",
    "Payload": { "id.$": "$.orderId", "customer.$": "$.customerName" }
  },
  "ResultSelector": { "processedId.$": "$.Payload.id", "status.$": "$.Payload.status" },
  "ResultPath": "$.processingResult",
  "OutputPath": "$.processingResult",
  "Next": "Ship"
}

After (JSONata):

"ProcessOrder": {
  "Type": "Task",
  "Resource": "arn:aws:states:::lambda:invoke",
  "Arguments": {
    "FunctionName": "arn:aws:lambda:us-east-1:123456789012:function:Process:$LATEST",
    "Payload": { "id": "{% $states.input.order.orderId %}", "customer": "{% $states.input.order.customerName %}" }
  },
  "Output": { "processedId": "{% $states.result.Payload.id %}", "status": "{% $states.result.Payload.status %}" },
  "Next": "Ship"
}

Pass State

Before (JSONPath):

"InjectDefaults": {
  "Type": "Pass",
  "Result": { "region": "us-east-1" },
  "ResultPath": "$.config",
  "Next": "Go"
}

After (JSONata):

"InjectDefaults": {
  "Type": "Pass",
  "Assign": { "region": "us-east-1" },
  "Next": "Go"
}

Choice State

JSONPath uses Variable + typed operators. JSONata uses a single Condition expression.

Before (JSONPath):

"Choices": [
  { "Variable": "$.status", "StringEquals": "approved", "Next": "Approved" },
  { "And": [
    { "Variable": "$.priority", "StringEquals": "high" },
    { "Variable": "$.age", "NumericLessThanEquals": 30 }
  ], "Next": "FastTrack" },
  { "Not": { "Variable": "$.email", "IsPresent": true }, "Next": "RequestEmail" }
]

After (JSONata):

"Choices": [
  { "Condition": "{% $states.input.status = 'approved' %}", "Next": "Approved" },
  { "Condition": "{% $states.input.priority = 'high' and $states.input.age <= 30 %}", "Next": "FastTrack" },
  { "Condition": "{% $not($exists($states.input.email)) %}", "Next": "RequestEmail" }
]

Choice Operator Mapping

Wait State

Before (JSONPath):

{ "Type": "Wait", "TimestampPath": "$.deliveryDate", "Next": "Check" }

After (JSONata):

{ "Type": "Wait", "Timestamp": "{% $states.input.deliveryDate %}", "Next": "Check" }

Map State

After (JSONata):

"ProcessItems": {
  "Type": "Map",
  "Items": "{% $states.input.orderData.items %}",
  "ItemSelector": {
    "item": "{% $states.context.Map.Item.Value %}",
    "index": "{% $states.context.Map.Item.Index %}"
  },
  "MaxConcurrency": 5,
  "ItemProcessor": {
    "ProcessorConfig": { "Mode": "INLINE" },
    "StartAt": "Process",
    "States": {
      "Process": {
        "Type": "Task",
        "Resource": "arn:aws:states:::lambda:invoke",
        "Arguments": { "FunctionName": "arn:aws:lambda:us-east-1:123456789012:function:Process:$LATEST", "Payload": "{% $states.input %}" },
        "Output": "{% $states.result.Payload %}",
        "End": true
      }
    }
  },
  "Assign": { "processedItems": "{% $states.result %}" },
  "Next": "Done"
}

Converting Intrinsic Functions

Converting Catch Blocks

JSONPath Catch uses ResultPath. JSONata Catch uses Assign and Output with $states.errorOutput.

Before (JSONPath):

"Catch": [{ "ErrorEquals": ["States.ALL"], "ResultPath": "$.error", "Next": "HandleError" }]

After (JSONata):

"Catch": [{
  "ErrorEquals": ["States.ALL"],
  "Assign": { "errorInfo": "{% $states.errorOutput %}" },
  "Output": "{% $states.input %}",
  "Next": "HandleError"
}]

Retry syntax is identical between JSONPath and JSONata — no conversion needed.

Conversion Pitfalls and How to Avoid Them

1. Do not mix JSONPath and JSONata fields in the same state

Invalid combinations: Arguments + InputPath, Output + ResultSelector, Condition + Variable. Remove all JSONPath fields from converted states.

2. You must remove .$ suffixes

❌  "orderId.$": "{% $states.input.orderId %}"
✓  "orderId": "{% $states.input.orderId %}"

3. Use $states instead of $ or $$.

❌  "{% $.orderId %}"        ❌  "{% $$.Task.Token %}"
✓  "{% $states.input.orderId %}"   ✓  "{% $states.context.Task.Token %}"

Note: $ is valid inside nested filter expressions (e.g., $states.input.items[$.price > 10]).

4. Do not use double quotes inside JSONata expressions

❌  "{% $states.input.status = "active" %}"
✓  "{% $states.input.status = 'active' %}"

5. Do not attempt to access the output of Assign or Output in the same state where they are assigned.

Assign and Output evaluate in parallel — new variable values are not available until the next state.

❌  "Assign": { "total": "{% $states.result.Payload.total %}" },
    "Output": { "total": "{% $total %}" }
✓  "Assign": { "total": "{% $states.result.Payload.total %}" },
    "Output": { "total": "{% $states.result.Payload.total %}" }

6. Use defensive coding to prevent undefined errors in JSONata

JSONPath silently returns null. JSONata throws States.QueryEvaluationError:

❌  "{% $states.input.customer.middleName %}"
✓  "{% $exists($states.input.customer.middleName) ? $states.input.customer.middleName : '' %}"

7. Use defensive coding to prevent invalid filter results

JSONata returns a single object (not a 1-element array) when exactly one item matches a filter, and undefined when nothing matches. Both break Map state Items and functions like $count:

❌  "Items": "{% $states.input.orders[status = 'pending'] %}"
✓  "Items": "{% ( $f := $states.input.orders[status = 'pending']; $type($f) = 'array' ? $f : $exists($f) ? [$f] : [] ) %}"

8. Iterator → ItemProcessor rename

Iterator was renamed to ItemProcessor and requires ProcessorConfig:

❌  "Iterator": { "StartAt": "...", "States": {...} }
✓  "ItemProcessor": { "ProcessorConfig": { "Mode": "INLINE" }, "StartAt": "...", "States": {...} }

Conversion Workflow

For each state being converted, apply these steps in order:

1. Add "QueryLanguage": "JSONata" to the state
2. Parameters → Arguments: remove .$ suffixes from all keys, wrap values in {% %}, replace $ with $states.input and $$ with $states.context
3. Convert ResultPath based on its value:
   • Absent or "$" → no action needed (default behavior is replaced by Output)
   • null → add "Output": "{% $states.input %}"
   • "$.field" → add "Assign": { "field": "{% $states.result %}" } and "Output": "{% $states.input %}"
4. ResultSelector → fold selection logic into Output (reference $states.result)
5. OutputPath → fold into Output (return only what you need)
6. Reminder: If the state has ResultSelector + ResultPath + OutputPath, collapse all three into a single Output field
7. Remove all five JSONPath I/O fields: InputPath, Parameters, ResultSelector, ResultPath, OutputPath
8. Convert *Path fields to base field + {% %} expression (TimeoutSecondsPath → TimeoutSeconds, HeartbeatSecondsPath → HeartbeatSeconds, ItemsPath → Items)
9. Replace States.* intrinsic functions with JSONata equivalents (see Converting Intrinsic Functions table)
10. Choice states: replace Variable + comparison operators with a single Condition expression
11. Map states: Iterator → ItemProcessor with ProcessorConfig, ItemsPath → Items, Parameters with $$.Map.* → ItemSelector with $states.context.Map.*
12. Catch blocks: replace ResultPath with Assign + Output using $states.errorOutput
13. Pass states: replace Result with Output or Assign
14. Where multiple consecutive states used ResultPath to thread data through the payload, refactor to use Assign variables instead — downstream states reference $variableName directly
15. Validate the converted state using the TestState API
16. Repeat for all states, then promote "QueryLanguage": "JSONata" to the top level and remove per-state declarations