Validation error for Step Function using Eventbridge Connection with definition substitution

[btyrrell-mn]

Describe the bug

I am getting a SCHEMA_VALIDATION_ERROR when using aws stepfunctions validate-state-machine-definition on a local definition file that is deployed using SAM.

The validator returns that the ConnectionArn is not valid when I am passing it as a definition substitution.

Regression Issue

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

Expected Behavior

The validator should pass as this is a definition substitution.

Current Behavior

Schema validation on the state machine fails.

Reproduction Steps

CloudFormation snippet:

  Workflow:
    Type: AWS::Serverless::StateMachine
    Properties:
      DefinitionUri: state_machines/workflow.asl.yaml
      DefinitionSubstitutions:
        ApiUrl: !Sub "https://redacted.url.com"
        ApiConnectionArn: !GetAtt APIConnection.Arn

Step Function state YAML:

        Get Database Details:
          Type: Task
          Resource: arn:aws:states:::http:invoke
          Arguments:
            ApiEndpoint: "{% '${ApiUrl}/v1/resource/' & $resource_id %}"
            Method: GET
            Authentication:
              ConnectionArn: ${ApiConnectionArn}
          Assign:
            response: "{% $states.result.ResponseBody %}"
          Next: Next Step

Here is the validation error:

{
    "result": "FAIL",
    "diagnostics": [
        {
            "severity": "ERROR",
            "code": "SCHEMA_VALIDATION_FAILED",
            "message": "The value for the 'ConnectionArn' field is not valid",
            "location": "/States/HTTP API Request/Arguments"
        }
    ],
    "truncated": false
}

Possible Solution

The validation should not error on definition substitutions.

Additional Information/Context

No response

CLI version used

2.33.16

Environment details (OS name and version, etc.)

macOS 26.2

[adev-code]

Hello @btyrrell-mn, thanks for reaching out. I have tried the command with "ConnectionArn": "${ApiConnectionArn}", the service returned an error and error body (not AWS CLI):

$ aws stepfunctions validate-state-machine-definition \
    --definition /state-machine.json \
    --region us-east-1 \
    --debug

2026-02-06 09:58:19,600 - MainThread - urllib3.connectionpool - DEBUG - https://states.us-east-1.amazonaws.com:443 "POST / HTTP/1.1" 200 626
2026-02-06 09:58:19,601 - MainThread - botocore.parsers - DEBUG - Response headers: {'x-amzn-RequestId': 'REDACTED', 'Date': 'Fri, 06 Feb 2026 17:58:19 GMT', 'Content-Type': 'application/x-amz-json-1.0', 'Content-Length': '626', 'connection': 'keep-alive'}
2026-02-06 09:58:19,601 - MainThread - botocore.parsers - DEBUG - Response body:
b'{"diagnostics":[{"code":"SCHEMA_VALIDATION_FAILED","location":"/States/HTTP API Request","message":"The QueryLanguage is set to \'JSONPath\', but field \'Arguments\' is only supported for the \'JSONata\' QueryLanguage","severity":"ERROR"},{"code":"SCHEMA_VALIDATION_FAILED","location":"/States/HTTP API Request/Resource","message":"Parameters field is required for resource ARN: arn:aws:states:::http:invoke","severity":"ERROR"},{"code":"SCHEMA_VALIDATION_FAILED","location":"/States/HTTP API Request/Arguments","message":"The value for the \'ConnectionArn\' field is not valid","severity":"ERROR"}],"result":"FAIL","truncated":false}'
2026-02-06 09:58:19,603 - MainThread - awscli.formatter - DEBUG - RequestId: REDACTED
{
    "result": "FAIL",
    "diagnostics": [
        {
            "severity": "ERROR",
            "code": "SCHEMA_VALIDATION_FAILED",
            "message": "The QueryLanguage is set to 'JSONPath', but field 'Arguments' is only supported for the 'JSONata' QueryLanguage",
            "location": "/States/HTTP API Request"
        },
        {
            "severity": "ERROR",
            "code": "SCHEMA_VALIDATION_FAILED",
            "message": "Parameters field is required for resource ARN: arn:aws:states:::http:invoke",
            "location": "/States/HTTP API Request/Resource"
        },
        {
            "severity": "ERROR",
            "code": "SCHEMA_VALIDATION_FAILED",
            "message": "The value for the 'ConnectionArn' field is not valid",
            "location": "/States/HTTP API Request/Arguments"
        }
    ],
    "truncated": false
}

Then when using actual ARN, it works:

$ aws stepfunctions validate-state-machine-definition \
    --definition /state-machine.json \
    --region us-east-1 \
    --debug

2026-02-06 10:12:06,259 - MainThread - urllib3.connectionpool - DEBUG - https://states.us-east-1.amazonaws.com:443 "POST / HTTP/1.1" 200 50
2026-02-06 10:12:06,259 - MainThread - botocore.parsers - DEBUG - Response headers: {'x-amzn-RequestId': 'REDACTED', 'Date': 'Fri, 06 Feb 2026 18:12:06 GMT', 'Content-Type': 'application/x-amz-json-1.0', 'Content-Length': '50', 'connection': 'keep-alive'}
2026-02-06 10:12:06,259 - MainThread - botocore.parsers - DEBUG - Response body:
b'{"diagnostics":[],"result":"OK","truncated":false}'
2026-02-06 10:12:06,259 - MainThread - awscli.formatter - DEBUG - RequestId: REDACTED
{
    "result": "OK",
    "diagnostics": [],
    "truncated": false
}

It seems that for now the service only accepts real ARN and not a substitute. Could you please confirm if it works fine if you set the actual ARN rather than substitution? Also, please confirm if the above repro and response was the same as yours both for using substitution and using actual ARN? If so, this issue would be converted to feature-request and see if the service could add this. Thank you.

[btyrrell-mn]

I can confirm that it validates if it is an ARN. I would like to note that other fields throughout a Step Function definition where the value is a resource ARN do not fail if I use a definition substitution. This is an inconsistency.