THE LINUX FOUNDATION PROJECTS

The Future of API-Driven Workflows: The Arazzo Specification

The Arazzo Specification is a community-driven open specification within the OpenAPI Initiative, a Linux Foundation Collaborative Project.

The Arazzo Specification defines a standard, programming language-agnostic mechanism to express sequences of calls and articulate the dependencies between them to achieve a particular outcome, or set of outcomes, when dealing with API descriptions (such as OpenAPI and AsyncAPI descriptions).

The Arazzo Specification can articulate these workflows in a deterministic human-readable and machine-readable manner, thus improving provider and consumer experiences when working with APIs. Similar to what OpenAPI has done for describing HTTP interfaces, the Arazzo Specification enables the ability to articulate the functional use cases offered by an API (or group of APIs) thus removing the guesswork for both human and machine consumers.

Use cases for machine-readable API workflow definition documents include, but are not limited to:

  • Interactive, living workflow documentation.
  • Automated documentation generation (e.g. Developer Portal documentation).
  • MCP, SDK, and code generation driven by functional use cases.
  • Automation of test cases (use-case or scenario specific testing end-to-end).
  • Automated regulatory compliance checks.
  • Guided developer onboarding — structured integration paths that show developers not just what an API can do, but how to use it to complete a real task, reducing time-to-first-successful-call and support burden for API providers.
  • Safe, predictable AI agent execution — agents follow explicit, validated workflows with defined inputs, outputs, and success criteria rather than inferring multi-step intent from individual endpoint descriptions, enabling reliable and auditable automation.
  • Orchestration of multi-step workflows by AI agents across HTTP and event-driven APIs.

The Arazzo Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear workflow interactions with APIs described using the OpenAPI Specification or AsyncAPI.

This GitHub project is the starting point for Arazzo including how to participate. You can also access the latest Arazzo Specification here.

 

How Does Arazzo Fit in the Open Initiative Specifications?

The OpenAPI Initiative now maintains three complementary specifications:

  • OpenAPI describes individual HTTP APIs.
  • Arazzo describes how those APIs — and event-driven APIs described with AsyncAPI — are combined into workflows: sequences of calls with explicit dependencies, inputs, outputs, and conditions.
  • Overlays provides a way to repeatably apply transformations to one or many API descriptions.

Together, the three specifications provide a complete picture of your API surface: what operations exist, how they are composed into meaningful workflows, and how those descriptions can be adapted for different consumers and contexts.

This matters more than ever as AI agents become first-class API consumers. An agent that can discover and reason over a well-described workflow is significantly more capable and reliable than one inferring intent from individual endpoints. Arazzo makes workflows a first-class, machine-readable artifact — deterministic enough for automation, expressive enough for humans.

An unpublished or unconsumed API creates value for no one. Arazzo helps close that gap.

 

The Arazzo Specification at Version 1.1.0

Building on the strong foundation of Arazzo 1.0, Arazzo Specification version 1.1.0 brings a host of new features.

This minor release delivers on something the community has been eagerly anticipating: AsyncAPI support.

For the first time, Arazzo workflows can declaratively describe sequences of calls that span both synchronous and asynchronous APIs — a workflow can now coordinate HTTP operations alongside event-driven interactions, all in a single machine-readable document. Alongside that headline addition, version 1.1 brings meaningful improvements to workflow composition, data selection, and several areas of specification precision that practitioners raised during the 1.0 lifecycle.

Summary of Changes

Here’s a quick summary of the headline changes in Arazzo 1.1.0:

  • AsyncAPI support. The sourceDescriptions object now accepts asyncapi documents alongside openapi and arazzo Async steps define a send or receive action, support correlation identifiers for request/response linking, timeouts, and explicit step dependencies via dependsOn.
  • Chained workflow execution. Action Objects now fully support calling other workflows, with explicit input mapping via a parameters This makes it straightforward to compose reusable sub-workflows — such as token refresh flows — into larger sequences.
  • Advanced Selector support. A new Selector Object enables precise, fine-grained data extraction from structured data using jsonpath, xpath, or jsonpointer. Selectors are available across workflow outputs, step outputs, request body payloads, and parameter values. The Expression Type Object (renamed from Criterion Expression Type Object) allows pinning a specific expression language version where required.
  • OpenAPI 3.2 alignment. The Parameter Object gains a querystring option for the in field, aligning with the equivalent feature in OpenAPI 3.2 and enabling the full URL query string to be treated and mapped as a single value.
  • Identity-based referencing. A new $self field at the root of an Arazzo description provides a canonical URI for the document. Implementations referencing an Arazzo description by URI must use $self if present, removing ambiguity in multi-document workflow systems.
  • Clarification improvements. A complete ABNF grammar for runtime expressions, explicit source description resolution ordering, and formally defined Truthy/Falsy evaluation semantics for success criteria conditions.

Upgrade Process

Arazzo 1.1.0 is a minor release. Existing Arazzo 1.0.x documents remain valid and no structural changes have been made to the core workflow description model.

If you are adopting any of the new features — particularly AsyncAPI source descriptions or the Selector Object — you will need to update your arazzo version field to 1.1.0. For tool vendors, we recommend reviewing the release notes on GitHub to assess any impact on parsers, validators, or execution engines.

As always, we recommend that tooling makers avoid locking to a specific minor version where possible, as our intent is to maintain backward compatibility across the 1.x line.

A Growing Ecosystem

The Arazzo tooling ecosystem has expanded significantly since the 1.0 release. Editors, validators, parsers, resolvers, generators, and standalone workflow execution engines are all available. To make tool discovery easier, we’ve added a comprehensive listing to the Arazzo repository README. This complements the openapi.tools website, which has also recently added Arazzo-specific tooling listings.

Looking Ahead

With Arazzo 1.1.0 delivered, work is already underway on future versions.

The proposed roadmap includes:

  • Support for gRPC, GraphQL, SOAP, MCP, and A2A step types.
  • Actor-in-loop support (human or agent) for workflows requiring approval or intervention.
  • Transformer and function support.
  • Loops.

We anticipate continuing to evolve the specification at a measured but steady pace. As with the 1.x line to date, backward compatibility will be preserved across minor releases.

 

Acknowledgements

This release would not have been possible without the contributions of our community. The engagement and stewardship shown by contributors across issues, pull requests, community calls, and discussions continues to drive the evolution of Arazzo forward. Thank you to everyone who has played a part — your efforts are genuinely appreciated.

We’d like to give particular thanks to the Arazzo Specification editors, who have worked tirelessly to drive, coordinate, and prepare this release. Special thanks Naresh Jain, Dmytro Anansky, Vladimir Gorej, and Henry Andrews for their significant contributions and feedback to this version.

Thank you all for making Arazzo version 1.1.0 a reality!

 

Joining the OpenAPI Initiative

Want to contribute to the future development of the Arazzo Specification by becoming a member of the OpenAPI Initiative? Find more information here.

While you think about it, please checkout these resources:

About the OpenAPI Initiative

The OpenAPI Initiative was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor-neutral description format. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software.

The OpenAPI Initiative has grown to a multi-specification that, first and foremost, provides the OpenAPI Specification, the most popular API description language available to API providers and consumers. The OpenAPI Initiative also supports the development of the Arazzo Specification, which caters for complex workflows invoking many APIs, and the Overlay Specification which provides the means to deterministically and reliably update an OpenAPI description through automation.

To learn what OpenAPI can do for you please visit our What is OpenAPI page.

About Linux Foundation

Founded in 2000, the Linux Foundation is supported by more than 1,000 members and is the world’s leading home for collaboration on open source software, open standards, open data, and open hardware. Linux Foundation projects like Linux, Kubernetes, Node.js and more are considered critical to the development of the world’s most important infrastructure. Its development methodology leverages established best practices and addresses the needs of contributors, users and solution providers to create sustainable models for open collaboration. For more information, please visit us at the Linux Foundation homepage.