What is the Arazzo specification?

It is an OpenAPI Initiative standard for describing sequences of API calls and their dependencies in a machine-readable way. It complements OpenAPI rather than replacing it.

Does Arazzo replace OpenAPI?

No. Arazzo complements OpenAPI by grouping related API calls into explicit, ordered workflows that OpenAPI alone cannot express.

How does an Arazzo workflow capture dependencies between API calls?

Each step defines parameters, success criteria such as a 200 status code, and outputs that later steps reuse, so calls run in the right order with data passed between them.

Weave API workflow using Arazzo: OpenAPI's new spec

This is human generated content.

What Arazzo spec is (and isn’t)
Getting started with Arazzo
How to structure an Arazzo specification
Conclusion
Work with Weesho Lapara
Additional resources

OpenAPI describes individual endpoints well, but most real integrations are a sequence: log in, fetch a resource, act on it. OpenAPI has no native, machine-readable way to express that a set of calls belong to one workflow, which leaves the ordering and data passing to prose or to each consumer to rediscover. The Arazzo specification fills that gap. If you already publish OpenAPI-based reference docs, Arazzo is the layer that turns those endpoints into described, machine-readable journeys.

What Arazzo spec is (and isn’t)

The Arazzo specification groups a series of APIs that are part of the same workflow. It provides a standard, programming language-agnostic mechanism to express sequences of API calls and their dependencies. Arazzo allows you to weave together these calls, articulating the relationships between them. Here’s what Arazzo is:

The Arazzo specification is a mechanism for defining sequences of API calls and expressing their dependencies.

The Arazzo specification is not a replacement for OpenAPI; it complements it. Where OpenAPI documents what each endpoint does, Arazzo documents how endpoints combine into a workflow, in a form tools can read and execute.

Getting started with Arazzo

To start using Arazzo, you need to create a separate file for your Arazzo specification. Like OAS, Arazzo specifications are typically written in YAML or JSON. And, you don’t need a pre-written OpenAPI description to create an Arazzo spec, but having one can help you map your API calls effectively.

How to structure an Arazzo specification

Arazzo specification isn’t drastically different from the way you write OAS. However, the initiative has determined the need to introduce a few new objects to make the workflow possible. The diagram below shows a high level overview of how the specification is structured.

Arazzo Specification Structure

An Arazzo workflow is built from ordered steps. Each step names the operation it calls, maps in parameters, checks a successCriteria (such as $statusCode == 200), and exposes outputs that later steps can reference, which is how dependencies and data passing are captured.

The key elements of the these structure are:

Structured Sequences: Arazzo allows you to define the workflow of API calls explicitly, making it easier to understand the flow.
Dependencies: You can express dependencies between calls, ensuring proper execution order using the step objects.
Outcome-Oriented: Arazzo focuses on achieving specific outcomes by weaving together calls as shown by the successCriteria and outputs objects.

arazzo: 1.0.0

  info:
    title: My Awesome API Workflow
    version: 1.0.0

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

  workflow:
  - workflowId: loginUserAndRetrievePet
    summary: Login User and then retrieve pets
    inputs:
        type: object
        properties:
            username:
                type: string
            password:
                type: string

    steps:

      - stepId: loginStep
        operationId: loginUser
        parameters:
          - name: username
            in: query
            value: $inputs.username
          - name: password
            in: query
            value: $inputs.password
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          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.loginUser.outputs.sessionToken
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          # outputs from this step
          availablePets: $response.body

      outputs:
          available: $steps.getPetStep.availablePets

Clear, accurate examples like this are what developers actually evaluate tools on, the same standard that applies to REST API documentation. Because an Arazzo document is machine-readable, it also serves both human readers and the tooling and agents that consume your API, which is the same principle behind writing docs for humans and AI agents.

Conclusion

Arazzo gives the API ecosystem a shared, machine-readable way to describe multi-step workflows that OpenAPI alone cannot express. Adopting it alongside your existing OpenAPI definitions makes complex integrations easier to document, test, and automate, without throwing away anything you already maintain.

Work with Weesho Lapara

If you want help describing your API workflows or modernising your developer docs, we can help. Book a consult or get in touch and we will map out a plan for your documentation.