(aws-stepfunctions): Unable to use JSONata expression for Map MaxConcurrency parameter

[zackcolello]

Describe the bug

It looks like there's a discrepancy between the expected data type of the maxConcurrency parameter of step functions Map construct between Cloudformation and CDK:

• AWS documentation reports that it's valid for MaxConcurrency to be a JSONata expression: In JSONata states, you can specify a JSONata expression that evaluates to an integer. (documentation)
• in aws-cdk, the data type is a number explicitly:

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

  Line 105 in 7c6914a

  readonly maxConcurrency?: number;

Regression Issue

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

Last Known Working CDK Library Version

No response

Expected Behavior

I expect to be able to pass in a valid JSONata expression string for the maxConcurrency parameter of state machine / step functions Map construct, based on the AWS documentation.

Current Behavior

Currently, trying to pass a JSONata expression string as the value for this parameter in CDK results in an error shaped like this (in my case, python): TypeError: type of argument max_concurrency must be one of (int, float, NoneType); got str instead

I've worked around this by using JSONPath instead (which has its own limitations for my use case), but I wanted to flag this discrepancy here for visibility.

Reproduction Steps

Passing in any valid JSONata expression for maxConcurrency of the Map construct results in the above error.

Possible Solution

No response

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.224.0

AWS CDK CLI version

2.1032.0

Node.js Version

22.14.0

OS

OSX

Language

Python

Language Version

3.12.12

Other information

No response

[pahud]

Hi @zackcolello,

Thank you for reporting this. I've confirmed this is a valid gap in CDK's JSONata support for Step Functions Map states.

Confirmed: AWS Step Functions documentation explicitly states:

"In JSONata states, you can specify a JSONata expression that evaluates to an integer" for MaxConcurrency

Current CDK limitation: The maxConcurrency property only accepts number type, blocking JSONata expressions.

Related issues: This is part of a broader pattern:

• (aws-stepfunctions): Can't add Jsonata strings to toleratedFailurePercentage #34085 - Same issue for toleratedFailurePercentage
• stepfunctions: Map.ItemSelector doesn't accept JSONata #34538 - Was fixed for itemSelector by adding jsonataItemSelector

The fix would likely follow the established pattern of adding a jsonataMaxConcurrency?: string property alongside the existing maxConcurrency?: number.

Making this a p2. Please help us prioritize with 👍 and we welcome PRs.