The Arazzo Specification v1.1.0

This object MAY be extended with Specification Extensions.

arazzo: 1.1.0
$self: https://api.example.com/workflows/pet-purchase.arazzo.yaml
info:
  title: A pet purchasing workflow
  summary: This Arazzo Description showcases the workflow for how to purchase a pet through a sequence of API calls
  description: |
      This Arazzo Description walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet.
  version: 1.0.1
sourceDescriptions:
- name: petStoreDescription
  url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
  type: openapi
- name: asyncOrderApiDescription
  url: https://raw.githubusercontent.com/OAI/Arazzo-Specification/main/examples/1.1.0/pet-asyncapi.yaml
  type: asyncapi

workflows:
- workflowId: loginUserAndRetrievePet
  summary: Login User and then retrieve pets
  description: This workflow lays out the steps to login a user and then retrieve pets
  inputs:
      type: object
      properties:
          username:
              type: string
          password:
              type: string
          orderCorrelationId:
              type: string
  steps:
  - stepId: loginStep
    description: This step demonstrates the user login step
    operationId: $sourceDescriptions.petstoreDescription.loginUser
    parameters:
      # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
      - name: username
        in: query
        value: $inputs.username
      - name: password
        in: query
        value: $inputs.password
    successCriteria:
      # assertions to determine step was successful
      - condition: $statusCode == 200
    outputs:
      # outputs from this step
      tokenExpires: $response.header.X-Expires-After
      rateLimit: $response.header.X-Rate-Limit
      sessionToken: $response.body
  - stepId: getPetStep
    description: retrieve a pet by status from the GET pets endpoint
    operationPath: '{$sourceDescriptions.petstoreDescription.url}#/paths/~1pet~1findByStatus/get'
    parameters:
      - name: status
        in: query
        value: 'available'
      - name: Authorization
        in: header
        value: $steps.loginStep.outputs.sessionToken
    successCriteria:
      - condition: $statusCode == 200
    onSuccess:
      - name: 'noPetsAvailable'
        type: "end"
        criteria:
          - condition: $response.body#/0 == null
    outputs:
      petId: $response.body#/0/id
  - stepId: purchasePetStep
    description: purchase a pet by posting an message on place-order channel
    operationPath: $sourceDescriptions.asyncOrderApiDescription.placeOrder
    action: send
    parameters:
    - name: orderCorrelationId
      in: header
      value: $inputs.orderCorrelationId
    requestBody:
      contentType: application/json
      payload:
        petId: $steps.getPetStep.outputs.petId
  - stepId: confirmPetPurchaseStep
    description: confirm the purchase of a pet
    operationPath: $sourceDescriptions.asyncOrderApiDescription.confirmOrder
    correlationId: $inputs.orderCorrelationId
    timeout: 6000
    action: receive
    outputs:
      orderId: $message.payload.orderId
  outputs:
      orderId: $steps.confirmPetPurchaseStep.outputs.orderId

This object MAY be extended with Specification Extensions.

title: A pet purchasing workflow
summary: This workflow showcases how to purchase a pet through a sequence of API calls
description: |
    This workflow walks you through the steps of searching for, selecting, and purchasing an available pet.
version: 1.0.1

This object MAY be extended with Specification Extensions.

name: petStoreDescription
url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
type: openapi

This object MAY be extended with Specification Extensions.

workflowId: loginUser
summary: Login User
description: This workflow lays out the steps to login a user
inputs:
    type: object
    properties:
        username:
            type: string
        password:
            type: string
steps:
  - stepId: loginStep
    description: This step demonstrates the user login step
    operationId: loginUser
    parameters:
      # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
      - name: username
        in: query
        value: $inputs.username
      - name: password
        in: query
        value: $inputs.password
    successCriteria:
        # assertions to determine step was successful 
        - condition: $statusCode == 200
    outputs:
        # outputs from this step
        tokenExpires: $response.header.X-Expires-After
        rateLimit: $response.header.X-Rate-Limit
outputs:
    tokenExpires: $steps.loginStep.outputs.tokenExpires

This object MAY be extended with Specification Extensions.

The dependsOn field at the step level is primarily intended to coordinate asynchronous operations.

For steps that reference AsyncAPI operations (via operationId or channelPath), tools will send or receive messages on the specified channel as defined by the referenced AsyncAPI description. For AsyncAPI send operations, the step completes immediately after the message is sent. Arazzo does not model broker acknowledgment or delivery confirmation. For AsyncAPI receive operations, step completion depends on message receipt as described below.

Because AsyncAPI channels MAY define multiple message types, and because message payloads MAY represent either success or failure conditions, authors SHOULD define successCriteria for AsyncAPI receive steps to explicitly evaluate the received message payload (for example, via $message.payload) and determine whether the step succeeded.

Authors MAY omit successCriteria only when both of the following conditions are met:

• The channel defines a single message type that unambiguously represents successful completion
• The message payload does not contain fields indicating error states (e.g., status codes or error flags)

When successCriteria is omitted, receiving any message matching the correlationId (if specified) within the timeout period is considered a successful step completion.

If correlationId is specified, only messages matching the correlation identifier are considered. If no matching message is received within the timeout period, the step fails and triggers any defined onFailure actions.

A single step example:

stepId: loginStep
description: This step demonstrates the user login step
operationId: loginUser
parameters:
    # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
    - name: username
      in: query
      value: $inputs.username
    - name: password
      in: query
      value: $inputs.password
successCriteria:
    # assertions to determine step was successful
    - condition: $statusCode == 200
outputs:
    # outputs from this step
    tokenExpires: $response.header.X-Expires-After
    rateLimit: $response.header.X-Rate-Limit

A multiple step example:

steps:
  - stepId: loginStep
    description: This step demonstrates the user login step
    operationId: loginUser
    parameters:
        # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
      - name: username
        in: query
        value: $inputs.username
      - name: password
        in: query
        value: $inputs.password
    successCriteria:
        # assertions to determine step was successful
      - condition: $statusCode == 200
    outputs:
        # outputs from this step
        tokenExpires: $response.header.X-Expires-After
        rateLimit: $response.header.X-Rate-Limit
        sessionToken: $response.body
  - stepId: getPetStep
    description: retrieve a pet by status from the GET pets endpoint
    operationPath: '{$sourceDescriptions.petStoreDescription.url}#/paths/~1pet~1findByStatus/get'
    parameters:
      - name: status
        in: query
        value: 'available'
      - name: Authorization
        in: header
        value: $steps.loginStep.outputs.sessionToken
    successCriteria:
      - condition: $statusCode == 200
    outputs:
        # outputs from this step
        availablePets: $response.body

An async step example:

- stepId: placeOrder
  description: This step demonstrates the action of sending a message payload to place an order
  operationId: $sourceDescriptions.asyncOrderApi.placeOrder
  action: send
  parameters:
      - name: requestId
        in: header
        value: $inputs.correlationId
  requestBody:
      payload:
          productId: $inputs.productDetails.productId
          quantity: $inputs.productDetails.quantity
- stepId: confirmOrder
  description: This step demonstrates the action of receiving a message payload to confirm an order
  operationId: $sourceDescriptions.asyncOrderApi.confirmOrder
  correlationId: $inputs.correlationId
  action: receive
  dependsOn:
    - placeOrder
  timeout: 6000
  outputs:
      orderId: $message.payload.orderId

This object MAY be extended with Specification Extensions.

# Query Example
- name: username
  in: query
  value: $inputs.username

# Querystring Example (application/x-www-form-urlencoded)
- name: searchParams
  in: querystring
  value: "filter=active&sort=desc&limit=50"

# Querystring with Runtime Expressions (application/x-www-form-urlencoded)
- name: fullQuery
  in: querystring
  value: "category={$inputs.category}&minPrice={$inputs.minPrice}&inStock=true"

# Querystring Example (application/json)
- name: filterParams
  in: querystring
  value: '{"filter":"active","sort":"desc","limit":50}'
  
# Header Example
- name: X-Api-Key
  in: header
  value: $inputs.x-api-key

This object MAY be extended with Specification Extensions.

name: JoinWaitingList
type: goto
stepId: joinWaitingListStep
criteria:
    # assertions to determine if this success action should be executed
    - context: $response.body
      condition: $[?count(@.pets) > 0]
      type: jsonpath

This object MAY be extended with Specification Extensions.

name: retryStep
type: retry
retryAfter: 1
retryLimit: 5
criteria:
    # assertions to determine if this action should be executed
    - condition: $statusCode == 503

This object MAY be extended with Specification Extensions.

All the fixed fields declared above are objects that MUST use keys that match the regular expression: ^[a-zA-Z0-9\.\-_]+$. The key is used to refer to the input or parameter in other parts of the Workflow Description.

Field Name Examples:

User
User_1
User_Name
user-name
my.org.User

components:
  parameters:
    storeId:
      name: storeId
      in: header
      value: $inputs.x-store-id
  inputs:
    pagination:
      type: object
      properties:
        page:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
  failureActions:
    refreshToken:
      name: refreshExpiredToken
      type: retry
      retryAfter: 1
      retryLimit: 5
      workflowId: refreshTokenWorkflowId
      criteria:
          # assertions to determine if this action should be executed
          - condition: $statusCode == 401       

"components": {
  "parameters": {
    "storeId": {
      "name": "storeId",
      "in": "header",
      "value": "$inputs.x-store-id"
    }
  },
  "inputs": {
    "pagination": {
      "type": "object",
      "properties": {
        "page": {
          "type": "integer",
          "format": "int32"
        },
        "pageSize": {
          "type": "integer",
          "format": "int32"
        }
      }
    }
  },
  "failureActions": {
    "refreshToken": {
      "name": "refreshExpiredToken",
      "type": "retry",
      "retryAfter": 1,
      "retryLimit": 5,
      "workflowId": "refreshTokenWorkflowId",
      "criteria": [
        {
          "condition": "$statusCode == 401"
        }
      ]
    }
  }
}

This object cannot be extended with additional properties and any properties added MUST be ignored.

  reference: $components.successActions.notify

  {
    "reference": "$components.successActions.notify"
  }

  reference: $components.parameters.page
  value: 1

  {
    "reference": "$components.parameters.page",
    "value": 1
  }

As part of a condition expression, you can use boolean, null, number, or string data types.

String comparisons MUST be case insensitive.

For simple conditions, Runtime Expressions can be used directly within the condition field:

# Direct usage in simple conditions
successCriteria:
  - condition: $statusCode == 200
  - condition: $response.body.count > $inputs.threshold

For regex, jsonpath, and xpath conditions, runtime expressions MUST be embedded within the condition string using {} curly braces. The runtime expressions are evaluated first, then substituted into the condition string before the expression is evaluated:

# Embedded expressions in JSONPath
successCriteria:
  - context: $response.body
    condition: '$[?(@.status == "{$inputs.expectedStatus}")]'
    type: jsonpath

# Embedded expressions in XPath
successCriteria:
  - context: $response.body
    condition: '/root/items[price > {$steps.getPricing.outputs.minPrice}]'
    type: xpath

# Embedded expressions in Regex
successCriteria:
  - context: $response.body.status
    condition: '^({$inputs.statusPattern})$'
    type: regex

The evaluation order is as follows:

• Runtime expressions within {} are evaluated and converted to strings
• The resulting string is the final condition expression
• The condition expression is evaluated according to its type (regex, jsonpath, xpath)
• The result is converted to pass/fail per Condition Evaluation

The entire condition string MUST be quoted when it contains embedded expressions to ensure proper YAML parsing.

When runtime expressions are embedded in strings, type conversion follows the rules defined in Runtime Expressions.

A condition specified in a Criterion Object MUST evaluate to a pass (truthy) or fail (falsy) state. The evaluation semantics depend on the type of condition.

# Pass if status code is 200
- condition: $statusCode == 200

# Pass if status code is 200 AND body contains data
- condition: $statusCode == 200 && $response.body.data != null

# Pass if status code starts with 2 (any 2xx code)
- context: $statusCode
  condition: '^2\d{2}$'
  type: regex

# Pass if response body contains at least one pet
- context: $response.body
  condition: $[?count(@.pets) > 0]
  type: jsonpath

# Pass if any pets array has elements
- context: $response.body
  condition: $.pets[*]
  type: jsonpath

# Pass if count of pets is greater than 0 (returns boolean)
- context: $response.body
  condition: count(/root/pets/*) > 0
  type: xpath

# Pass if pets node exists (returns node-set)
- context: $response.body
  condition: /root/pets
  type: xpath

successCriteria:
  # Both conditions must pass
  - condition: $statusCode == 200
  - context: $response.body
    condition: $.data[*]
    type: jsonpath

This object MAY be extended with Specification Extensions.

A simple Condition example:

- condition: $statusCode == 200

A regex Condition example:

- context: $statusCode
  condition: '^200$'
  type: regex

A JSONPath Condition example:

- context: $response.body
  condition: $[?count(@.pets) > 0]
  type: jsonpath

The supported expression selector types and versions are as follows:

When used to specify a particular version of JSONPath or XPath, implementations MUST apply the semantics defined in that version’s specification. This includes:

• Query syntax, filter expressions, and function behavior for JSONPath as defined in the specified version.
• Expression syntax, function library, and type conversion rules (including Effective Boolean Value) for XPath as defined in the specified version.

For Criterion Object condition evaluation, the version-specific Effective Boolean Value (EBV) rules MUST be used when evaluating XPath expressions:

• XPath 3.1 (default): Section 19.1.2 - Effective Boolean Value
• XPath 3.0: Section 2.4.3 - Effective Boolean Value
• XPath 2.0: Section 2.4.3 - Effective Boolean Value
• XPath 1.0: Section 4.2 - Boolean Conversions

If this object is not defined, the default version for the selector type MUST be used.

This object MAY be extended with Specification Extensions.

A JSONPath example:

  type: jsonpath
  version: draft-goessner-dispatch-jsonpath-00

An XPath example:

  type: xpath
  version: xpath-30

An output example:

  outputs:
    userEmail:
      context: $response.body
      selector: $.user.profile.email
      type: jsonpath

A Step RequestBody example:

  requestBody:
    contentType: application/json
    payload:
      invoiceId:
        context: $steps.fetchXml.outputs.invoiceXml
        selector: /Invoice/Header/InvoiceNumber
        type:
          type: xpath
          version: xpath-30

This object MAY be extended with Specification Extensions.

A JSON templated example:

  contentType: application/json
  payload: |
    {
      "petOrder": {
        "petId": "{$inputs.pet_id}",
        "couponCode": "{$inputs.coupon_code}",
        "quantity": "{$inputs.quantity}",
        "status": "placed",
        "complete": false
      }
    }

A JSON object example:

  contentType: application/json
  payload: 
    petOrder:
      petId: $inputs.pet_id
      couponCode: $inputs.coupon_code
      quantity: $inputs.quantity
      status: placed
      complete: false

A complete Runtime Expression example:

  contentType: application/json
  payload: $inputs.petOrderRequest

An XML templated example:

  contentType: application/xml
  payload: |
    <petOrder>
      <petId>{$inputs.pet_id}</petId>
      <couponCode>{$inputs.coupon_code}</couponCode>
      <quantity>{$inputs.quantity}</quantity>
      <status>placed</status>
      <complete>false</complete>
    </petOrder>

A Form Data example:

  contentType: application/x-www-form-urlencoded
  payload: 
    client_id: $inputs.clientId
    grant_type: $inputs.grantType
    redirect_uri: $inputs.redirectUri
    client_secret: $inputs.clientSecret
    code: $steps.browser-authorize.outputs.code
    scope: $inputs.scope  

A Form Data String example:

  contentType: application/x-www-form-urlencoded
  payload: "client_id={$inputs.clientId}&grant_type={$inputs.grantType}&redirect_uri={$inputs.redirectUri}&client_secret={$inputs.clientSecret}&code{$steps.browser-authorize.outputs.code}&scope=$inputs.scope}"

If targetSelectorType is omitted, then:

• target MUST be interpreted as JSON Pointerif the payload is application/json.
• target MUST be interpreted as XPath Expression if the payload is application/xml or another XML-based media type.

This object MAY be extended with Specification Extensions.

A Runtime Expression example:

  target: /petId
  value: $inputs.pet_id

A literal example:

  target: /quantity
  value: 10

A JSONPath example using an Expression Type Object:

  target: $.items[?(@.sku=='ABC123')].quantity
  targetSelectorType: jsonpath
  value:
    context: $steps.getInventory.outputs.payload
    selector: $.newQuantity
    type: jsonpath

An XPath example using older XPATH 3.0:

  target: /Envelope/Header/CustomerId
  targetSelectorType:
    type: xpath
    version: xpath-30
  value:
    context: $steps.fetchCustomerData.outputs.xml
    selector: /CustomerInfo/Id
    type:
      type: xpath
      version: xpath-30