stepfunctions: Map.ItemSelector doesn't accept JSONata

[TomasChmelik]

Describe the bug

The Map.ItemSelector doesn't support specifying JSONata while it being supported by AWS when configuring it manually.

I have following step function definition in AWS:

{
  "StartAt": "Map",
  "States": {
    "Map": {
      "Type": "Map",
      "ItemProcessor": {
        "ProcessorConfig": {
          "Mode": "INLINE"
        },
        "StartAt": "Pass",
        "States": {
          "Pass": {
            "Type": "Pass",
            "End": true
          }
        }
      },
      "End": true,
      "QueryLanguage": "JSONata",
      "ItemSelector": "{% $merge([$states.input, {\"item\": $states.context.Map.Item.Value}]) %}",
      "Items": "{% $states.input.data %}"
    }
  }
}

The map step passes full input (without needing to specify every individual property) while also adding map's item as new property to the input.

So if input of state machine is

{
  "data": ["a", "b"],
  "other": "c"
}

then first Pass step will get following in the input:

{
  "data": ["a", "b"],
  "other": "c",
  "item": "a"
}

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

No error during synthesis

Current Behavior

Synthesis error: TypeError: type of argument item_selector must be one of (Mapping[str, Any], NoneType); got str instead

Reproduction Steps

aws_stepfunctions.Map(
    self,
    'Map',
    query_language=aws_stepfunctions.QueryLanguage.JSONATA,
    items=aws_stepfunctions.ProvideItems.jsonata('{% $states.input.data %}'),
    item_selector='{% $merge([$states.input, {"item": $states.context.Map.Item.Value}]) %}',
)

Possible Solution

• Extend restricted type to string as well
• Provide some helper function which will accept JSONata string and which will be accepted by type checking

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.198.0

AWS CDK CLI version

2.1016.1 (build 6de56b2)

Node.js Version

v22.9.0

OS

Ubuntu

Language

Python

Language Version

Python 3.13.3

Other information

No response

[pahud]

Root Cause Analysis

After examining the CDK source code, specifically the Map state implementation in map.ts and map-base.ts, the issue stems from two main factors:

aws-cdk/packages/aws-cdk-lib/aws-stepfunctions/lib/states/map-base.ts

Line 114 in ce88c76

readonly itemSelector?: { [key: string]: any };

aws-cdk/packages/aws-cdk-lib/aws-stepfunctions/lib/states/map-base.ts

Lines 225 to 229 in ce88c76

	private renderItemSelector(): any {
	if (!this.itemSelector) return undefined;
	return FieldUtils.renderObject({
	ItemSelector: this.itemSelector,
	});

The CDK implementation enforces that itemSelector must be an object type (Mapping[str, Any]), while Step Functions natively supports both object mappings and JSONata expressions as strings. This type constraint is causing the synthesis error when trying to use a JSONata expression string.

Possible Fixes/Solutions

This seems to be a valid solution.

// Create a helper class similar to ProvideItems
export abstract class ProvideItemSelector {
  public static fromJsonata(expression: string): ProvideItemSelector { 
    return { itemSelector: expression }; 
  }
  public static fromObject(mapping: {[key: string]: any}): ProvideItemSelector { 
    return { itemSelector: mapping }; 
  }
  public abstract readonly itemSelector: any;
}

I'm making it a p1 as there no existing workaround but we would love to have any PR contributions from the community.

Let me know if you need any clarification or assistance.

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.