What is the Arazzo Specification and how does it relate to OpenAPI? #

Modern APIs are rarely used in isolation. Real-world integrations require sequencing multiple API calls, passing data between them, and making decisions based on intermediate results. The Arazzo Specification, released by the OpenAPI Initiative in 2024, was created to address precisely this need. It defines a standard, machine-readable format for describing multi-step API workflows — sequences of API calls that together accomplish a meaningful business outcome.

The Problem Arazzo Solves #

OpenAPI excels at describing individual API operations: what endpoint to call, what parameters to provide, and what response to expect. But it has no native concept of workflow — the ordered set of operations required to complete a business process.

Consider a common e-commerce flow:

1. Authenticate — POST to /auth/token to get an access token.
2. Search for a product — GET /products?q=shoes using the token.
3. Add to cart — POST /cart/items with the selected product ID from step 2.
4. Place order — POST /orders with the cart ID from step 3.

Each step depends on the output of the previous one. Documenting this flow requires prose documentation, diagrams, or custom scripting — none of which are machine-readable or interoperable. Arazzo changes that.

What Arazzo Adds to the OpenAPI Ecosystem #

Arazzo is not a replacement for OpenAPI. It is a companion specification that sits on top of one or more OpenAPI documents and describes how their operations should be sequenced and composed. An Arazzo document references OpenAPI source documents and defines workflows that orchestrate calls to those operations.

Together, OpenAPI and Arazzo serve different layers of API description:

Core Concepts #

arazzo Version Field #

Like OpenAPI, every Arazzo document declares its version:

arazzo: 1.0.0

info Object #

Provides metadata about the workflow document:

info:
  title: E-Commerce Purchase Workflow
  version: 1.0.0
  description: Describes the sequence of steps to complete a product purchase.

sourceDescriptions #

Declares the OpenAPI (or other Arazzo) documents that provide the operations used in this workflow:

sourceDescriptions:
  - name: ecommerce-api
    url: ./openapi.yaml
    type: openapi

workflows #

The heart of an Arazzo document. Each workflow has an id, a summary, optional inputs (defined as a JSON Schema), and a list of steps:

workflows:
  - workflowId: purchase-product
    summary: Complete a product purchase from search to order confirmation
    inputs:
      type: object
      properties:
        searchQuery:
          type: string
        userId:
          type: string
    steps:
      - stepId: search-products
        operationId: ecommerce-api.searchProducts
        parameters:
          - name: q
            in: query
            value: $inputs.searchQuery
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          firstProductId: $response.body#/products/0/id

      - stepId: add-to-cart
        operationId: ecommerce-api.addCartItem
        requestBody:
          payload:
            productId: $steps.search-products.outputs.firstProductId
            quantity: 1
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          cartId: $response.body#/cartId

Steps and operationId References #

Each step references an operation from a source OpenAPI document using the format {sourceDescription.name}.{operationId}. This tight coupling with OpenAPI’s operationId field underscores why assigning unique, descriptive operation IDs in OpenAPI documents is a best practice.

successCriteria #

Each step can define success criteria — conditions that must be satisfied for the step to be considered successful before proceeding. These use a simple expression language that can reference the HTTP status code, response headers, and response body:

successCriteria:
  - condition: $statusCode == 200
  - condition: $response.body#/status == 'active'

outputs #

Steps can declare outputs — named values extracted from the response that can be referenced by later steps. This is how data flows between steps, replacing the need for out-of-band scripting:

outputs:
  userId: $response.body#/id
  authToken: $response.header.Authorization

onFailure and onSuccess #

Arazzo supports conditional branching based on step outcomes. The onFailure and onSuccess fields define what to do next: proceed to a specific step, end the workflow, or retry the current step:

onFailure:
  - name: handle-auth-failure
    type: goto
    stepId: refresh-token

Runtime Expressions #

Arazzo uses a concise runtime expression language to reference values at execution time:

• $inputs.fieldName — workflow-level input
• $steps.stepId.outputs.outputName — output from a previous step
• $response.body#/jsonPointer — value extracted from the current step’s response body using JSON Pointer (RFC 6901)
• $response.header.HeaderName — response header value
• $statusCode — HTTP status code of the current step’s response

How Arazzo Differs from AsyncAPI and BPMN #

It is worth distinguishing Arazzo from related standards:

• AsyncAPI — describes event-driven and asynchronous APIs (message queues, WebSockets, Kafka). Arazzo focuses on synchronous HTTP API workflows.
• BPMN (Business Process Model and Notation) — a heavyweight standard for modeling business processes, often used with enterprise workflow engines. Arazzo is lightweight, API-centric, and developer-friendly.
• Postman Collections — a tool-specific format for grouping API requests. Arazzo is tool-agnostic and specification-grade.

Tooling and Adoption #

As a 2024 release, Arazzo’s tooling ecosystem is still developing, but early adoption is underway:

• Redocly — one of the first commercial API platforms to announce Arazzo support, integrating it into their workflow and documentation tooling.
• Speakeasy — supports Arazzo for generating SDK usage examples and end-to-end integration tests.
• Vacuum — an OpenAPI linter that has begun tracking Arazzo document validation.
• Community implementations — the OAI GitHub repository tracks reference implementations and tool support.

Why Arazzo Matters for API-First Teams #

For teams practicing API-first development, Arazzo completes the description layer:

• Documentation — workflows can be rendered as step-by-step guides in documentation portals, making complex integration scenarios understandable.
• Testing — machine-readable workflows can drive contract tests that validate multi-step integration scenarios automatically.
• SDK generation — tools like Speakeasy can generate higher-level SDK methods that encapsulate common workflows, improving developer experience.
• AI agents — Arazzo workflows can guide AI agents through multi-step API interactions without requiring bespoke orchestration code.

Conclusion #

The Arazzo Specification fills a critical gap in the OpenAPI ecosystem by providing a standard, machine-readable format for describing multi-step API workflows. Where OpenAPI documents what each API operation does, Arazzo documents how those operations are sequenced to accomplish real business goals. For teams building complex API integrations, exposing APIs to AI agents, generating SDKs, or automating end-to-end testing, Arazzo represents the next evolution of the API description landscape.

Last updated on April 29, 2026.