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 the first, additional, specification from OpenAPI
Now there are two specifications. The original and well known OpenAPI Specification, and now a separate but complimentary specification, Arazzo. 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. There are more additional specifications in progress with a goal to 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.