# Arazzo Specification

> A comprehensive, multi-section breakdown of the Arazzo specification, explaining workflows orchestration, input-output expressions, and state assertions.

Source: https://apiguide.dev/specifications/arazzo
Current version: 1.1.0
Official source: https://spec.openapis.org/arazzo/v1.1.0.html
Updated: 2026-10-14

## Introduction to Arazzo

The Arazzo Specification describes workflows and state transitions across multiple API operations. While the [OpenAPI Specification](/specifications/openapi) (OAS) defines individual endpoints, it lacks the context of how those endpoints are executed sequentially to achieve business tasks. 

Arazzo connects these dots by acting as a client workflow orchestrator.

The current version, 1.1.0, was published in May 2026. It adds [AsyncAPI](/specifications/asyncapi) source descriptions, so one workflow can mix HTTP calls with messages it sends and receives, support for the OpenAPI 3.2 `querystring` parameter location, a `$self` field for identifying the document, and JSONPath and XPath selectors wherever 1.0 accepted only [JSON Pointer](/specifications/json-pointer).

### The Workflow Orchestration Flow

An Arazzo workflow follows a clear sequential flow of execution:
1. **Inputs Initialization**: The client starts the workflow by supplying required context parameters (such as credentials, workspace domains, or entity names).
2. **Step 1 (User Creation)**: The client executes the first step (e.g., calling the user creation endpoint) and extracts the new User ID from the response.
3. **Step 2 (License Assignment)**: The client initiates the next step, feeding the extracted User ID into the request body to assign a product license, then extracts the generated workspace token from the response headers.
4. **Step 3 (Workspace Access)**: The client uses the workspace token in the Authorization header to call the workspace access endpoint.
5. **Outputs Resolution**: The workflow concludes, returning resolved final variables (like access URLs or organization details) to the client application.

---

## 1. Mapping Operations to Steps

Each workflow contains a series of **steps**. A step invokes an endpoint defined in the linked OpenAPI specification (`sourceDescription`).

For each step, Arazzo maps:
* **`parameters`**: HTTP headers, query variables, or cookies required by the endpoint.
* **`requestBody`**: Payloads sent in the request.
* **`outputs`**: Variable mappings extracted from the HTTP response headers or body for reuse in subsequent steps.

```yaml
steps:
  - stepId: generateToken
    operationId: authUser
    requestBody:
      payload:
        client_id: $inputs.clientId
        client_secret: $inputs.clientSecret
    outputs:
      accessToken: $response.body#/token
```

---

## 2. Dynamic Expressions Resolver

Arazzo uses a structured runtime expression syntax to dynamically resolve values at execution time.

| Expression Namespace | Source Description | Example |
| :--- | :--- | :--- |
| **`$statusCode`** | HTTP status code of the current step's response | `$statusCode == 201` |
| **`$inputs.*`** | Input parameters declared at workflow start | `$inputs.username` |
| **`$response.body#/*`** | Body fields returned in the current step, addressed by JSON Pointer | `$response.body#/id` |
| **`$response.header.*`** | HTTP response headers returned in the current step | `$response.header.Location` |
| **`$steps.<stepId>.outputs.*`**| Saved outputs from a previously executed step | `$steps.generateToken.outputs.accessToken` |

---

## 3. State Assertions (`successCriteria`)

To ensure that a workflow is progressing successfully, steps can define assertions. If the response does not satisfy the criteria, the step fails, and what happens next is decided by its `onFailure` actions (retry, go to another step, or end). With no `onFailure` defined, the default is to break and return.

* **`successCriteria`**: An array of logical checks. Every check must evaluate to true.

```yaml
steps:
  - stepId: checkInventory
    operationId: getInventory
    successCriteria:
      - condition: $statusCode == 200
      - condition: $response.body#/quantity > 0
```