Choice state

A Choice state ("type": "Choice") adds branching logic to a state machine.

In addition to the common state fields, Choice states introduce the following additional fields.

choices (Required)

An array of Choice Rules that determines which state the state machine transitions to next.

default (Optional, Recommended)

The name of the state to transition to if none of the transitions in Choices is taken.


Choice states don’t support the End field. In addition, they use Next only inside their Choices field.

Choice State Example

The following is an example of a Choice state and other states that it transitions to.


You must specify the $.type field. If the state input doesn’t contain the $.type field, the execution fails and an error is displayed in the execution history.

"example": {
  "type": "Choice",
  "choices": [{
      "not": {
        "Variable": "$.hello",
        "StringEquals": "world"
      "next": "get_assets"

In this example, the state machine starts with the following input value.

  "hello": "world"

Step Functions transitions to the ValueInTwenties state, based on the value field.

If there are no matches for the Choice state’s Choices, the state provided in the Default field runs instead. If the Default state isn’t specified, the execution fails with an error.

The following comparison operators are supported:

  • And

  • BooleanEquals

  • Not

  • NumericEquals

  • NumericGreaterThan

  • NumericGreaterThanEquals

  • NumericLessThan

  • NumericLessThanEquals

  • Or

  • StringEquals

  • StringGreaterThan

  • StringGreaterThanEquals

  • StringLessThan

  • StringLessThanEquals

  • TimestampEquals

  • TimestampGreaterThan

  • TimestampGreaterThanEquals

  • TimestampLessThan

  • TimestampLessThanEquals

For each of these operators, the corresponding value must be of the appropriate type: string, number, Boolean, or timestamp. Step Functions doesn’t attempt to match a numeric field to a string value. However, because timestamp fields are logically strings, it’s possible that a field considered to be a timestamp can be matched by a StringEquals comparator.


You can create complex, nested Choice Rules using And, Not, and Or. However, the Next field can appear only in a top-level Choice Rule.