Introducing 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 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)

code and SDK generation driven by functional use cases

automation of test cases

automated regulatory compliance checks

deterministic API invocation by AI-based LLMs

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 HTTP APIs described using the OpenAPI Specification.

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

Arazzo is an additional specification from OpenAPI

Now there are three specifications. The original and well known OpenAPI Specification, a separate but complimentary workflow specification (Arazzo) and recently an Overlay Specification. The OAS provides a description for a singular API and there are new versions in the pipeline. Arazzo provides a description for a group of APIs and their relationships. Overlays provides a way to repeatably apply transformations to one or many OpenAPI descriptions. The three specifications together provide a means for a more complete and versatile description of your API behaviors. Descriptions that can be leveraged by automation and code generation to reduce the labor and time needed to produce value. An undeployed or unconsumed API is not creating value for anyone.

Announcing Arazzo Specification version 1.0.1

In 2024, the OpenAPI Initiative set a high bar for activity with the release of new specifications like Arazzo 1.0.0 and Overlay 1.0.0, along with two important patch versions of the OpenAPI Specification: 3.1.1 and 3.0.4. Today, we’re excited to kick off 2025 on a strong note by announcing the release of Arazzo Specification version 1.0.1!

This 1.0.1 patch release introduces updates, clarifications, and expansions that refine the specification without altering its core functionality. While the way workflows are described in Arazzo remains unchanged, this release addresses areas where greater clarity was needed, improves examples for implementers, and corrects minor inaccuracies (as is typical with any initial 1.0.0 release).

Importantly, tooling built for Arazzo 1.0.0 will remain fully compatible with 1.0.1, as the patch release does not include any structural changes. This reflects our commitment to maintaining backward compatibility and supporting frequent, iterative improvements for the specification.

If you’re starting a new project or have the flexibility to upgrade, we highly recommend targeting Arazzo 1.0.1 as your version of choice!

Summary of changes

The 1.0.1 release brings important clarifications, improved and corrected examples, and addresses minor inaccuracies that appeared in the initial 1.0.0 release. In addition, we’ve introduced a non-authoritative JSON Schema representation of the Arazzo Specification, making it easier for implementers to validate documents programmatically.

Here’s a quick summary of the notable changes in Arazzo 1.0.1:

JSON Schema added for the Arazzo Specification 1.0.x.
JSON Schema test suite for validation and compliance.
Clarified the allowed types for the retryAfter fixed field within the Failure Action object.
Improved clarity around the use of workflowId across the Step, Success Action, and Failure Action objects.
Adopted RFC 9110 as the reference for Header Field guidance.
Adopted RFC 9110 for payload (or request content) guidance.
Fixed inaccuracies and typos in field descriptions within the Step Object and Parameter Object.
Removed redundant references to event-based message properties from the Runtime Expressions.

Upgrade process

For most users and tool vendors, no action is required—this patch release introduces only wording changes, clarifications, and corrections, with no structural changes to the specification.

That said, if you publish Arazzo tools or maintain workflows that rely on the specification, we recommend reviewing the release notes on GitHub to ensure everything aligns with your expectations. While the update should be seamless, it’s always a good idea to double-check for any changes relevant to your implementation.

Looking ahead

As noted earlier, we anticipate relatively frequent updates to the Arazzo specification. To ensure smooth adoption, we recommend that tooling makers avoid locking into a specific patch version of the specification, as all patch releases will remain backward compatible.

Looking ahead, we’re already making significant progress on the upcoming Arazzo 1.1.0 minor release. The primary focus of this release is to introduce support for AsyncAPI, enabling workflows to span APIs that leverage both HTTP and event-driven protocols. This exciting development will expand Arazzo’s capabilities, making it a more versatile and comprehensive solution for modern API ecosystems.

Acknowledgements

This release would not have been possible without the contributions of our vibrant, community-driven ecosystem. The active engagement and stewardship shown by our contributors continue to inspire and drive the evolution of Arazzo. While it’s not possible to name everyone individually, we want to extend our sincere thanks to everyone who has suggested an idea, raised a constructive issue, opened or reviewed a pull request, or participated in our regular calls or discussions. Your efforts have been invaluable, and we deeply appreciate your support and commitment!

We’d like to give particular thanks to the Arazzo Specification editors, who have worked tirelessly to drive, coordinate, and prepare releases for the specification. A special word of gratitude goes to Jeremy Fiel for his excellent work in providing the JSON Schema for Arazzo, and to Ralf Handl from the OpenAPI Initiative’s Technical Steering Committee, for his hands-on support and invaluable counsel in improving the infrastructural setup around the specification repository.

Thank you all for making Arazzo 1.0.1 a reality!