# Arazzo in OpenAPI best practices

# Arazzo: OpenAPI Workflows

The Arazzo Specification is a new addition to the OpenAPI Specification that allows you to define sequences of operations for your API.

An Arazzo description is a separate document that references your OpenAPI document and describes how to combine operations from your OpenAPI document into step-by-step sequences.

Arazzo descriptions are useful for:

- Defining complex sequences of operations that involve multiple API calls.
- Documenting the expected behavior of your API in a more structured way than a narrative description.
- Generating code to execute the sequences of operations.
- Generating tests to verify that the sequences of operations behave as expected.
- Generating documentation that explains how to use the sequences of operations.

## Arazzo Description Structure

An Arazzo description is a JSON or YAML document that follows the structure defined by the Arazzo Specification.

### Arazzo version

| Field Name | Type     | Required |
| ---------- | -------- | -------- |
| `arazzo`   | `string` | ✅       |

The version of the Arazzo Specification that the document uses. The value must be a supported [version number](#arazzo-specification-versions).

```yaml
workflowsSpec: 1.0.0-prerelease
```

### Info metadata

| Field Name | Type                        | Required |
| ---------- | --------------------------- | -------- |
| `info`     | [Info Object](#info-object) | ✅       |

Provides metadata about the Arazzo description.

```yaml
info:
  title: Speakeasy Bar Workflows
  summary: Workflows for managing the Speakeasy Bar API
  description: >
    This document defines workflows for managing the [Speakeasy Bar API](https://bar.example.com), including
    creating new drinks, managing inventory, and processing orders.
  version: 4.6.3
```

### Source description

| Field Name           | Type                                                      | Required |
| -------------------- | --------------------------------------------------------- | -------- |
| `sourceDescriptions` | [[Source Description Object](#source-description-object)] | ✅       |

An array of [source description objects](#source-description-object) defining the OpenAPI or other documents containing the operations referenced by the workflows. The array must contain at least one source.

```yaml
sourceDescriptions:
  - name: speakeasyBar
    url: https://bar.example.com/openapi.yaml
    type: openapi
  - name: printsAndBeeps
    url: https://output.example.com/workflows.yaml
    type: workflowsSpec
```

### Workflows

| Field Name  | Type                                  | Required |
| ----------- | ------------------------------------- | -------- |
| `workflows` | [[Workflow Object](#workflow-object)] | ✅       |

An array of [workflow objects](#workflow-object) defining the workflows. The array must contain at least one workflow.

```yaml
workflows:
  - workflowId: createDrink
    summary: Create a new drink in the bar's menu
    inputs:
      allOf:
        - $ref: "#/components/inputs/authenticate"
        - type: object
          properties:
            drink_name:
              type: string
            drink_type:
              type: string
            drink_price_usd_cent:
              type: integer
            ingredients:
              type: array
              items:
                type: string
    steps:
      - stepId: authenticate
        operationId: authenticate
        parameters:
          - reference: $components.parameters.username
          - reference: $components.parameters.password
      - stepId: createDrink
        operationId: createDrink
        parameters:
          - reference: $components.parameters.authorization
          - name: name
            in: query
            value: $inputs.drink_name
          - name: type
            in: query
            value: $inputs.drink_type
          - name: price
            in: query
            value: $inputs.drink_price_usd_cent
          - name: ingredients
            in: query
            value: $inputs.ingredients
  - workflowId: makeDrink
    summary: Order a drink and check the order status
    inputs:
      - name: orderType
        description: The type of order
        type: string
        required: true
      - name: productCode
        description: The product code of the drink
        type: string
        required: true
      - name: quantity
        description: The quantity of the drink
        type: integer
        required: true
    steps:
      - stepId: orderDrink
        operationId: createOrder
        parameters:
          - name: orderType
            in: body
            value: $inputs.orderType
          - name: productCode
            in: body
            value: $inputs.productCode
          - name: quantity
            in: body
            value: $inputs.quantity
      - stepId: checkStatus
        operationId: getOrder
        parameters:
          - name: orderNumber
            in: path
            value: $orderDrink.orderNumber
        successCriteria:
          - type: simple
            condition: $checkStatus.status == 'completed'
        onSuccess:
          - name: printReceipt
            type: goto
            workflowId: $sourceDescriptions.printsAndBeeps.printReceipt
            criteria:
              - type: simple
                condition: $checkStatus.status == 'completed'
        onFailure:
          - name: beepLoudly
            type: goto
            workflowId: $sourceDescriptions.printsAndBeeps.beepLoudly
            criteria:
              - type: simple
                condition: $checkStatus.status == 'failed'
  - workflowId: addIngredient
    summary: Add a new ingredient to the bar's inventory
    inputs:
      - name: username
        description: The username of the manager
        type: string
        required: true
      - name: password
        description: The password of the manager
        type: string
        required: true
      - name: ingredient_name
        description: The name of the ingredient
        type: string
        required: true
      - name: ingredient_type
        description: The type of the ingredient
        type: string
        required: true
      - name: ingredient_stock
        description: The stock of the ingredient
        type: integer
        required: true
      - name: productCode
        description: The product code of the ingredient
        type: string
        required: true
    steps:
      - stepId: authenticate
        operationId: authenticate
        parameters:
          - reference: $components.parameters.username
            value: admin
          - reference: $components.parameters.password
      - stepId: addIngredient
        operationId: createIngredient
        parameters:
          - reference: $components.parameters.authorization
          - name: name
            in: query
            value: $inputs.ingredient_name
          - name: type
            in: query
            value: $inputs.ingredient_type
          - name: stock
            in: query
            value: $inputs.ingredient_stock
          - name: productCode
            in: query
            value: $inputs.productCode
components:
  inputs:
    authenticate:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
  parameters:
    authorization:
      name: Authorization
      in: header
      value: $authenticate.outputs.token
    username:
      name: username
      in: body
      value: $inputs.username
    password:
      name: password
      in: body
      value: $inputs.password
```

This table shows all fields at the root of the Arazzo Specification:

## Arazzo Specification Versions

The `arazzo` field contains the version number of the Arazzo Specification that the document conforms to. Tooling should use this value to interpret the document correctly.

The current version of the Arazzo Specification is 1.0.0-prerelease, but keep in mind that the specification is still under development.

## Info Object

Provides metadata about the Arazzo description.

Below is an example of an `info` object in an Arazzo document:

```yaml filename="arazzo.yaml"
info:
  title: Speakeasy Bar Workflows
  summary: Workflows for managing the Speakeasy Bar API
  description: >
    This document defines workflows for managing the [Speakeasy Bar API](https://bar.example.com), including
    creating new drinks, managing inventory, and processing orders.
  version: 4.6.3
```

## Source Description Object

A source description points to an OpenAPI document containing the operations referenced by the workflows in this document. It may also reference other Arazzo documents.

Below is an example of two source description objects in an Arazzo description document:

```yaml filename="arazzo.yaml"
sourceDescriptions:
  - name: speakeasyBar
    url: https://bar.example.com/openapi.yaml
    type: openapi
  - name: printsAndBeeps
    url: https://output.example.com/workflows.yaml
    type: workflowsSpec
```

## Workflow Object

A workflow object defines a sequence of operations.

Below is an example of a workflow object:

```yaml filename="arazzo.yaml"  
workflows:
  - workflowId: createDrink
    summary: Create a new drink in the bar's menu
    inputs:
      allOf:
        - $ref: "#/components/inputs/authenticate"
        - type: object
          properties:
            drink_name:
              type: string
            drink_type:
              type: string
            drink_price_usd_cent:
              type: integer
            ingredients:
              type: array
              items:
                type: string
    steps:
      - stepId: authenticate
        operationId: authenticate
        parameters:
          - reference: $components.parameters.username
          - reference: $components.parameters.password
      - stepId: createDrink
        operationId: createDrink
        parameters:
          - reference: $components.parameters.authorization
          - name: name
            in: query
            value: $inputs.drink_name
          - name: type
            in: query
            value: $inputs.drink_type
          - name: price
            in: query
            value: $inputs.drink_price_usd_cent
          - name: ingredients
            in: query
            value: $inputs.ingredients
  - workflowId: makeDrink
    summary: Order a drink and check the order status
    inputs:
      - name: orderType
        description: The type of order
        type: string
        required: true
      - name: productCode
        description: The product code of the drink
        type: string
        required: true
      - name: quantity
        description: The quantity of the drink
        type: integer
        required: true
    steps:
      - stepId: orderDrink
        operationId: createOrder
        parameters:
          - name: orderType
            in: body
            value: $inputs.orderType
          - name: productCode
            in: body
            value: $inputs.productCode
          - name: quantity
            in: body
            value: $inputs.quantity
      - stepId: checkStatus
        operationId: getOrder
        parameters:
          - name: orderNumber
            in: path
            value: $orderDrink.orderNumber
        successCriteria:
          - type: simple
            condition: $checkStatus.status == 'completed'
        onSuccess:
          - name: printReceipt
            type: goto
            workflowId: $sourceDescriptions.printsAndBeeps.printReceipt
            criteria:
              - type: simple
                condition: $checkStatus.status == 'completed'
        onFailure:
          - name: beepLoudly
            type: goto
            workflowId: $sourceDescriptions.printsAndBeeps.beepLoudly
            criteria:
              - type: simple
                condition: $checkStatus.status == 'failed'
  - workflowId: addIngredient
    summary: Add a new ingredient to the bar's inventory
    inputs:
      - name: username
        description: The username of the manager
        type: string
        required: true
      - name: password
        description: The password of the manager
        type: string
        required: true
      - name: ingredient_name
        description: The name of the ingredient
        type: string
        required: true
      - name: ingredient_type
        description: The type of the ingredient
        type: string
        required: true
      - name: ingredient_stock
        description: The stock of the ingredient
        type: integer
        required: true
      - name: productCode
        description: The product code of the ingredient
        type: string
        required: true
    steps:
      - stepId: authenticate
        operationId: authenticate
        parameters:
          - reference: $components.parameters.username
            value: admin
          - reference: $components.parameters.password
      - stepId: addIngredient
        operationId: createIngredient
        parameters:
          - reference: $components.parameters.authorization
          - name: name
            in: query
            value: $inputs.ingredient_name
          - name: type
            in: query
            value: $inputs.ingredient_type
          - name: stock
            in: query
            value: $inputs.ingredient_stock
          - name: productCode
            in: query
            value: $inputs.productCode
```

## Step Object

A step object defines a single operation to perform as part of a workflow.

Below is an example of step objects in an Arazzo description document:

```yaml filename="arazzo.yaml"
steps:
      - stepId: orderDrink
        operationId: createOrder
        parameters:
          - name: orderType
            in: body
            value: $inputs.orderType
          - name: productCode
            in: body
            value: $inputs.productCode
          - name: quantity
            in: body
            value: $inputs.quantity
```

## Parameter Object

A parameter object defines a single parameter to pass to an operation in a workflow step.

### Parameter Location

For parameters passed to an operation, the `in` field specifies the location of the parameter. The possible values are:

- `path` - The parameter is part of the operation's URL path.
- `query` - The parameter is appended to the operation's URL as a query parameter.
- `header` - The parameter is sent in the request headers.
- `cookie` - The parameter is sent in a cookie.

For parameters passed to a workflow, the `in` field must be omitted. Workflow parameters are always passed in the workflow's `inputs` object.

### Arazzo Parameter Object Examples

```yaml filename="arazzo.yaml"
parameters:
  - reference: $components.parameters.authorization
  - name: name
    in: query
    value: $inputs.drink_name
  - name: type
    in: query
    value: $inputs.drink_type
  - name: price
    in: query
    value: $inputs.drink_price_usd_cent
  - name: ingredients
    in: query
    value: $inputs.ingredients
```

## Success Action Object

A success action object defines an action to take when a workflow step succeeds.

Below is an example of a success action object:

```yaml filename="arazzo.yaml"
onSuccess:
  - name: printReceipt
    type: goto
    workflowId: $sourceDescriptions.printsAndBeeps.printReceipt
    criteria:
      - type: simple
        condition: $checkStatus.status == 'completed'
```

## Failure Action Object

A failure action object defines an action to take when a workflow step fails.

Below is an example of a failure action object:

```yaml filename="arazzo.yaml"
onFailure:
  - name: beepLoudly
    type: goto
    workflowId: $sourceDescriptions.printsAndBeeps.beepLoudly
    criteria:
      - type: simple
        condition: $checkStatus.status == 'failed'
```

## Components Object

The `components` object holds reusable objects that can be referenced from other parts of the Arazzo description.

The keys in the `components` object may only contain alphanumeric characters, underscores, and dashes.

### Arazzo Components Object Example

```yaml filename="arazzo.yaml"  
components:
  inputs:
    authenticate:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
  parameters:
    authorization:
      name: Authorization
      in: header
      value: $authenticate.outputs.token
    username:
      name: username
      in: body
      value: $inputs.username
    password:
      name: password
      in: body
      value: $inputs.password
```

The components defined in an Arazzo description are scoped to that document. Components defined in one Arazzo description cannot be referenced from another Arazzo description.

## Reusable Object

A reusable object allows you to reference objects like success actions and failure actions defined in the `components` object from locations within steps or workflows.

### Arazzo Reusable Object Example

```yaml filename="arazzo.yaml"
- reference: $components.parameters.username
  value: admin
- reference: $components.parameters.password
```

## Criterion Object

A criterion object is used to specify assertions in the `successCriteria` field of a [step object](#step-object), or the `criteria` field of a [success action object](#success-action-object) or [failure action object](#failure-action-object).

Criterion objects support three types of assertions:

- `simple` - Basic comparisons using literals, operators, and [runtime expressions](#runtime-expressions). This is the default if no `type` is specified.
- `regex` - Applies a regular expression pattern to a context defined by a [runtime expression](#runtime-expressions).
- `JSONPath` - Applies a [JSONPath](https://goessner.net/articles/JsonPath/) expression to a context defined by a [runtime expression](#runtime-expressions). The root node of the JSONPath is the context.

### Literals

Literals are constant values that can be used in `simple` conditions. The following data types are supported:

### Operators

Simple conditions support the following operators:

<Table
  data={[
    {
      operator: "`<`",
      description: "Less than"
    },
    {
      operator: "`<=`",
      description: "Less than or equal"
    },
    {
      operator: "`>`",
      description: "Greater than"
    },
    {
      operator: "`>=`",
      description: "Greater than or equal"
    },
    {
      operator: "`==`",
      description: "Equal"
    },
    {
      operator: "`!=`",
      description: "Not equal"
    },
    {
      operator: "`!`",
      description: "Not"
    },
    {
      operator: "`&&`",
      description: "And"
    },
    {
      operator: "`||`",
      description: "Or"
    },
    {
      operator: "`()`",
      description: "Grouping"
    },
    {
      operator: "`[]`",
      description: "Array index (0-based)"
    },
    {
      operator: "`.`",
      description: "Property dereference"
    }
  ]}
  columns={[
    { key: "operator", header: "Operator" },
    { key: "description", header: "Description" }
  ]}
/>

String comparisons are case-insensitive.

A criterion object consists of the following fields:

### Arazzo Criterion Object Examples

**Simple Condition - Check if a drink was successfully created**

```yaml filename="arazzo.yaml"
- condition: $statusCode == 201
```

**Simple Condition - Check if the bar is open**

```yaml
- condition: $response.body#/isOpen == true
```

**Regex Condition - Check if the drink name matches a pattern**

```yaml filename="arazzo.yaml"
- context: $response.body#/drinkName
  condition: "^Sazerac"
  type: regex
```

**JSONPath Condition - Check if the ingredient list contains "whiskey"**

```yaml filename="arazzo.yaml"
- context: $response.body
  condition: $..ingredients[?(@.name == 'whiskey')]
  type: JSONPath
```

**Simple Condition - Check if the customer is over 21**

```yaml filename="arazzo.yaml"
- condition: $response.body#/customer/age >= 21
```

**JSONPath Condition - Check if there are any available tables**

```yaml filename="arazzo.yaml"
- context: $response.body
  condition: $[?length(@.tables[?(@.available == true)]) > 0]
  type: JSONPath
```

## Request Body Object

The request body object describes the payload and `Content-Type` to send with the request when executing an operation in a workflow step.

### Request Body Object Examples

**JSON Payload (Template)**

```yaml filename="arazzo.yaml"
contentType: application/json
payload: |
  {
    "order": {
      "drinkId": "{$inputs.drink_id}",
      "customerId": "{$inputs.customer_id}",
      "quantity": {$inputs.quantity}
    }
  }
```

**JSON Payload (Object)**

```yaml filename="arazzo.yaml"
contentType: application/json
payload:
  order:
    drinkId: $inputs.drink_id
    customerId: $inputs.customer_id
    quantity: $inputs.quantity
```

**JSON Payload (Runtime Expression)**

```yaml filename="arazzo.yaml"
contentType: application/json
payload: $inputs.orderPayload
```

**XML Payload (Template)**

```yaml filename="arazzo.yaml"
contentType: application/xml
payload: |
  <order>
    <drinkId>{$inputs.drink_id}</drinkId>
    <customerId>{$inputs.customer_id}</customerId>
    <quantity>{$inputs.quantity}</quantity>
  </order>
```

**Form Data Payload (Object)**

```yaml filename="arazzo.yaml"
contentType: application/x-www-form-urlencoded
payload:
  drinkId: $inputs.drink_id
  customerId: $inputs.customer_id
  quantity: $inputs.quantity
```

**Form Data Payload (String)**

```yaml filename="arazzo.yaml"
contentType: application/x-www-form-urlencoded
payload: "drinkId={$inputs.drink_id}&customerId={$inputs.customer_id}&quantity={$inputs.quantity}"
```

## Payload Replacement Object

A payload replacement object specifies a location within the request payload and the value to insert at that location.

### Payload Replacement Object Examples

**Runtime Expression Value**

```yaml
target: /drinkId
value: $inputs.drink_id
```

**Literal Value**

```yaml
target: /quantity
value: 2
```

## Runtime Expressions

Runtime expressions allow you to reference values that will be available when a workflow is executed, such as values from the HTTP request or response, the event that triggered the workflow, or outputs from previous workflow steps.

The syntax for runtime expressions is `{expression}`, where `expression` is one of the following:

### Runtime Expression Examples

## Arazzo Specification Extensions

The Arazzo Specification allows custom properties to be added at certain points using specification extensions.

Extension properties are always prefixed by `"x-"` and can have any valid JSON value.

For example:

```yaml
x-internal-id: abc123
x-vendor-parameter:
  vendorId: 123
  channelId: abc
```

The extensions defined by the Arazzo Specification are:

The specification extension key formats `^x-oai-` and `^x-oas-` are reserved for extensions defined by the [OpenAPI Initiative](https://www.openapis.org/).

Extension properties can be used to add additional features, metadata, or configuration options to the Arazzo description that are not directly supported by the current version of the specification. However, additional tooling may be required to process custom extensions.