ValidateStateMachineDefinition - AWS Step Functions


Validates the syntax of a state machine definition.

You can validate that a state machine definition is correct without creating a state machine resource. Step Functions will implicitly perform the same syntax check when you invoke CreateStateMachine and UpdateStateMachine. State machine definitions are specified using a JSON-based, structured language. For more information on Amazon States Language see Amazon States Language (ASL).

Suggested uses for ValidateStateMachineDefinition:

  • Integrate automated checks into your code review or Continuous Integration (CI) process to validate state machine definitions before starting deployments.

  • Run the validation from a Git pre-commit hook to check your state machine definitions before committing them to your source repository.


Errors found in the state machine definition will be returned in the response as a list of diagnostic elements, rather than raise an exception.

Request Syntax

{ "definition": "string", "type": "string" }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.


The Amazon States Language definition of the state machine. For more information, see Amazon States Language (ASL).

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1048576.

Required: Yes


The target type of state machine for this definition. The default is STANDARD.

Type: String


Required: No

Response Syntax

{ "diagnostics": [ { "code": "string", "location": "string", "message": "string", "severity": "string" } ], "result": "string" }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.


If the result is OK, this field will be empty. When there are errors, this field will contain an array of Diagnostic objects to help you troubleshoot.

Type: Array of ValidateStateMachineDefinitionDiagnostic objects


The result value will be OK when no syntax errors are found, or FAIL if the workflow definition does not pass verification.

Type: String

Valid Values: OK | FAIL


For information about the errors that are common to all actions, see Common Errors.


The input does not satisfy the constraints specified by an AWS service.

HTTP Status Code: 400


Validate an inline state machine definition

The following example shows how to invoke the API from the CLI:

aws stepfunctions validate-state-machine-definition \ --definition '{"StartAt":"WaitState","States":{"WaitState":{"Type":"Wait","Seconds":5,"End":true}}}' \ --type 'STANDARD'

Validate a state machine definition from a file

If your state machine definition is saved in a JSON file, you can use the file:// notation to pass the file contents to the API.

aws stepfunctions validate-state-machine-definition \ --definition file://my-state-machine-definition.asl.json

Parse the validation result

On POSIX compliant systems, you can use a command-line utility like grep to parse the output and generate a non-zero return code if the definition did not successfully pass the syntax check:

aws stepfunctions validate-state-machine-definition \ --definition file://my-state-machine-definition.asl.json | grep '"result": "OK"'

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: