oai/arazzo-specification

Arazzo Specification is an open specification that defines a standard, programming language-agnostic mechanism to express sequences of API calls and the dependencies between them to achieve specific outcomes.

The specification addresses the problem of documenting and automating complex API workflows by providing a deterministic, human-readable and machine-readable format for describing sequences of API interactions. It builds on the OpenAPI Specification model, extending it to capture not just individual API endpoints but the orchestrated workflows that combine multiple calls in a defined order. This enables both humans and machines to understand the functional use cases an API or group of APIs provides, removing ambiguity from workflow documentation and execution.

Organizations should adopt Arazzo when they need to document API workflows, generate interactive documentation, create SDKs driven by functional use cases, automate test case generation, or enable deterministic API invocation by AI systems. The specification works with both design-first and code-first development approaches and integrates with existing OpenAPI and AsyncAPI descriptions. It suits teams building complex multi-step API interactions where the sequence and dependencies between calls matter as much as the individual endpoints themselves.

The project is maintained as a community-driven specification within the OpenAPI Initiative under the Linux Foundation. Development activity shows ongoing engagement with the ecosystem, as evidenced by the growing collection of third-party tools including multiple editors and visualization tools from different organizations, workflow generators that analyze OpenAPI specifications to create Arazzo documents, and validation and linting tools. The specification itself has reached a stable release version and continues to evolve through community contribution and feedback.