Arazzo Specification – OpenAPI Initiative

3 min read Original article ↗

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.