bug: validate-state-machine-definition rejects valid state machine definitions #12958
Description
Is there an existing issue for this?
- I have searched the existing issues
Current Behavior
Valid state machine definitions that are accepted by AWS are rejected by LocalStack's `validate-state-machine-definition`. This issue occurs when the top-level QueryLanguage is set to JSONPath.
The following definition will be accepted in AWS, but won't in LocalStack.
{
"Comment": "A description of my state machine",
"StartAt": "Map",
"QueryLanguage": "JSONPath",
"States": {
"Map": {
"Type": "Map",
"QueryLanguage": "JSONata",
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "Pass",
"States": {
"Pass": {
"QueryLanguage": "JSONPath",
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}AWS's output
$ aws stepfunctions validate-state-machine-definition \
--definition file://example1.json
{
"result": "OK",
"diagnostics": [],
"truncated": false
}
LocalStack's Output
$aws stepfunctions validate-state-machine-definition \
--definition file://example1.json
{
"result": "FAIL",
"diagnostics": [
{
"severity": "ERROR",
"code": "SCHEMA_VALIDATION_FAILED",
"message": "Error=ValueError Args=['Cannot downgrade from JSONata context to a JSONPath context at: [325 313 793 783 288 330 325 313 250 238 232]'] in definition '{\n \"Comment\": \"A description of my state machine\",\n \"StartAt\": \"Map\",\n \"QueryLanguage\": \"JSONPath\",\n \"States\": {\n \"Map\": {\n \"Type\": \"Map\",\n \"QueryLanguage\": \"JSONata\",\n \"ItemProcessor\": {\n \"ProcessorConfig\": {\n \"Mode\": \"INLINE\"\n },\n \"StartAt\": \"Pass\",\n \"States\": {\n \"Pass\": {\n \"QueryLanguage\": \"JSONPath\",\n \"Type\": \"Pass\",\n \"End\": true\n }\n }\n },\n \"End\": true\n }\n }\n}\n'."
}
],
"truncated": false
}
According to AWS behavior:
- When the top-level `QueryLanguage` is `JSONPath`, any state can specify `JSONata` indivisually.
In LocalStack, however:
- If a state (including not only to the top-level state machine but also to Parallel or Map) specifies JSONata , none of its child states can use JSONPath.
Expected Behavior
Accepting the above definition.
How are you starting LocalStack?
With a docker run command
Steps To Reproduce
How are you starting localstack (e.g., bin/localstack command, arguments, or docker-compose.yml)
docker run localstack/localstack
Client commands (e.g., AWS SDK code snippet, or sequence of "awslocal" commands)
$ aws stepfunctions validate-state-machine-definition --definition file://example1.json
with above json.
Environment
- OS: macOS Sequoia 15.5
- LocalStack:
LocalStack version: 4.7.1.dev17
LocalStack build date: 2025-08-05
LocalStack build git hash: e62a727f8Anything else?
I think preprocessor.py’s handling of `QueryLanguage` should be updated:
Only disallow specifying `JSONPath` when the top-level `QueryLanguage` is `JSONata`.
If you agree with this approach, I’m happy to open a pull request with the fix.
What do you think?