The Arazzo Specification – A Deep Dive

Extracting value from API interactions often requires more than a single call to an endpoint to achieve the outcome desired. Until recently, the standards and specifications community offered little guidance on how to feasibly articulate multi-call expeditions across the endpoints exposed by either a single, or multiple APIs. Even when working with popular API specifications such as OpenAPI, teams often must craft human-centric guides to help improve an API consumers ability to achieve their integration work. To tackle this and other common practical challenges across the API landscape, projects like the OpenAPI initiative (OAI), expanded their areas of focus with the establishment of Special Interest Groups (SIGs), otherwise known as working groups. One such working group, focused on multi-step workflow scenarios, and their work resulted in the evolution of the OpenAPI Initiative into a multi-specification project with the launch of the Arazzo Specification 1.0.0 in May 2024. 

In fact, in 2024, the OAI set a new bar for activity with the release of not just Arazzo 1.0.0, but also Overlay 1.0.0, alongside two important patch versions of the OpenAPI Specification: 3.1.1 and 3.0.4. This momentum has carried forward into 2025, marked by the recent patch release for Arazzo  1.0.1. 

The Broader Use-Cases for Arazzo 

While Arazzo is a key enabler of AI-based API consumption, it also addresses several major challenges for API producers and consumers today: 

• Provide Deterministic API Consumption Recipes: Standardize workflows to ensure repeatable, structured API interactions. 
• Act as Living Workflow Documentation: Keep API workflows up to date without relying on outdated or external documentation. 
• Automate Consumer-facing Documentation: Reduce reliance on out-of-band documentation by generating developer portal docs dynamically. 
• Enable End-to-End Test Automation: Define API workflows that can be used for automated testing. 
• Streamline Regulatory Compliance Validation: Automate checks to verify API interactions against compliance requirements. 
• Empower Next-Generation API SDK Generation: Enable workflow-aware SDKs for improved developer experiences that focus on specific use cases. 
• Enable Agentic API Consumption: Provide a consistent and interoperable mechanism for AI models and agents to interact with APIs. 

The Arazzo Specification does not mandate a specific development process such as design-first  or code-first. Instead, it facilitates either technique by establishing clear workflow interactions with HTTP APIs described using the OpenAPI Specification (and in the future it’s planned to expand to event-based protocols and the AsyncAPI specification).

Now that we’ve grounded ourselves in some of the many use cases for Arazzo, let’s dive in and take a closer look at the specification itself.  

Figure 1 - The Arazzo Specification Logo 

The Arazzo Specification Structure 

The Arazzo Specification describes an approach to document use-case oriented workflows in a programmatically readable format. The formats supported by Arazzo are YAML and JSON, thus they are machine-readable while also being sufficiently human-readable. When we talk about a workflow in the context of Arazzo, we define it as a series of API calls that, when woven together accomplish some business objective. 

The additional human readable nature of Arazzo improves the ability of API providers to tell the story of their API(s) in a manner that can improve consumer experiences. Arazzo deliberately caters to human developers and improves their developer experience (DX). At the same time, Arazzo is fully aware of the needs of AI-agents and simultaneously improves the agent experience (AX) by providing the deterministic semantics needed for them to parse and execute complex and/or sensitive API workflows. 

If you are familiar with the OpenAPI Specification (OAS), or indeed its sister specification AsyncAPI, then the Arazzo Specification should feel familiar to you. One noticeable deviation relates to how referencing reusable components works within Arazzo. Rather than using the OpenAPI $ref mechanism (which clashes with the JSON Schema keyword $ref), Arazzo uses a runtime expression syntax to specify references which are not a JSON Schema object (for JSON Schema object referencing, continue to use $ref as that’s well defined in the JSON Schema). Rather than put the details here, you can check out the GitHub issue for more information. 

In most cases, the various conventions and patterns around metadata objects, reusable components, and the specification’s language itself should feel familiar. 

Even the image below (a specification on a page style) should look familiar to you! 

Figure 2 - Arazzo Specification - 1.0.1 

Crafting an Arazzo description means we will create (either by hand or preferably as the output of low-code, no-code, or natural language processing tooling) a YAML or JSON document which conforms to the Arazzo Specification. This means that at a minimum, for a document to be classified as a valid Arazzo document, it must contain a valid Arazzo Specification field (e.g. `arazzo: 1.0.1`), an `info` field, a `sourcesDescriptions` field with at least one defined Source Description Object, and there must be at least one Workflow defined in the `workflows` field.  

In the sections below, we’ll cover all of this. Don’t worry, it’s not complicated! 

The Arazzo Specification Object 

This is the root object of the Arazzo description. It identifies the version of the Arazzo Specification used, various metadata, and the workflows which represent what can be parsed, rendered, and/or executed by the processing software. 

Figure 3 - Arazzo Specification Object - Minimal Example 

The example above provides a minimalist example of a valid Arazzo document. The document contains a valid `arazzo` version, it specifies a `sourceDescriptions` which in this case references an OpenAPI description on a remote sever, and it defines a workflow which has at least one step.  

The Arazzo specification is versioned using a major.minor.patch versioning scheme. At the time of writing, the available versions of Arazzo are 1.0.1 (released Jan 2025) and 1.0.0 (released May 2024).  

Field Name	Description	Required
arazzo	The version of the Arazzo Specification that the Arazzo Description uses.	Yes
info	Provides metadata about the workflows contain within the Arazzo Description.	Yes
sourceDescriptions	A list of source descriptions (such as an OpenAPI description) the workflow defined will apply to.	Yes
workflows	A list of workflows to be applied to various API endpoints defined in the sourceDescriptions.	Yes
components	Various reusable elements/schemas for the Arazzo Description – help reduce verbosity.	No

Arazzo Structure – Info Object 

The Info Object contains metadata about the defined Arazzo document. The information is useful for discoverability, building up a catalog or marketplace for use-case orientated capabilities that have been described using Arazzo.  

Figure 4 - Arazzo Specification - Info Example 

The example above provides a rich Info Object example, where the title, summary, and description fields set clear context for consumers so they can understand what is possible with the current Arazzo Document. The version field represents the version of the current document which is not to be confused with the version of the Arazzo Specification itself! 

Field Name	Description	Required
title	A human readable title for the Arazzo document.	Yes
summary	A short summary of what can be achieved.	No
description	A description of the purpose of the workflows defined.	No
version	The version identifier of the document (this is not the version of the Specification to which the document conforms).	Yes

Arazzo Structure – Source Description Object 

An Arazzo document contains a sourceDescriptions property which is an array of Source Description Objects. It lists the source descriptions, which can either be an OpenAPI description or another Arazzo document and can be referenced by one or more of the workflows defined. From a programming language perspective, it’s best to think of these akin to namespaces or imports. They set the scope (or boundary) to which workflows in the entry Arazzo document can be applied to.

Figure 5 - Arazzo Specification - SourceDescriptions Example 

In the example above, two OpenAPI sourceDescriptions are specified. Any workflow defined can have steps which interact with operations in either or both OpenAPI descriptions referenced. This is very powerful! 

Field Name	Description	Required
name	A unique name for the source description.	Yes
url	A URL to a source description to be used by a workflow. It can be relative to the Arazzo document.	Yes
type	The type of source description. Possible values are "openapi" or "arazzo". It’s planned to add “asyncapi” into the future!	No

Arazzo Structure – Workflow Object 

An Arazzo document can contain one of more Workflow Objects which are specified in the workflows property. These describe the workflows to be taken across one or more APIs to achieve a specific objective or outcome. What’s powerful about workflows is that the steps they defined can comprise of calls to API endpoints/operations hosted across multiple APIs. The steps within a workflow may also call other workflows, meaning that it’s trivial to chain complex multi-workflow orchestrations together while still ensuring modularity, better maintenance, and testability. 

Figure 6 - Arazzo Specification - Workflows Example 

In the partial example above a single workflow is defined. The workflowId uniquely defines the workflow, while the summary and description, give consumers context for what use case is covered by the workflow.  

In the sections below, we’ll jump into the details of the other properties. 

Field Name	Description	Required
workflowId	Unique string to represent the workflow.	Yes
summary	Specifies the purpose or objective of the workflow.	No
description	A description of the workflow.	No
inputs	Inputs needed by the workflow to function (e.g. an API Key or a token, or a destination you want to fly to). What’s needed is described using JSON Schema.	No
dependsOn	A list of workflows that need be completed before this workflow can be processed.	No
steps	An ordered list of steps. Each step represents a call to an API operation or to another workflow.	Yes
successActions	A list of success actions that are applicable for all steps described under this workflow. Think of these as things to do if a step succeed (maybe we to raise an event upon every successful step completion).	No
failureActions	A list of failure actions that are applicable for all steps in this workflow. A good example is that if a step fails because an authentication token is expired, then let’s refresh the token and retry the step. Rather than having this in each step, we have it here for convenience!	No
outputs	These are things to return from the workflow and can processed by the calling software application or agent.	No
parameters	A list of parameters that are applicable for all steps described under this workflow.	No

Arazzo Structure – Workflow Inputs 

It’s common that a workflow might need to be provided various inputs that it cannot determine itself. For example, if I wanted to book a trip away, then I would need to provide a destination, dates, cost range (and many more) human inputs. Additionally, the software executing the workflow might needed to also pass in secure credentials for API invocation etc. Arazzo caters for this flexibly by allowing the inputs to be described using an JSON Schema object. 

Figure 7 - Arazzo Specification - Workflow Inputs Example 

In the example above, a JSON Schema object describes the expected inputs for the workflow. In this case, four string inputs are specified with three of them being required. 

Arazzo Structure – Step Object 

The steps within a workflow represent the most important part of the Arazzo document. Each step represents either a call to an API operation, or to another workflow. The latter enabling workflows to be modular and allowing authors build more complex workflows by leveraging other predefined or discoverable workflows at the step level. As an example, if a workflow exists for obtaining an OAuth 2.0 Bearer Token, then it would be advantageous to leverage that rather than having to inline the fully Authorization Code Flow negotiation into each workflow created.  

Figure 8 - Arazzo Specification - Steps Example 

In the partial example above, we have a searchPets step containing a clear description. The step is going to call the getPets operation within the petsAPI defined in the sourceDescriptions. The syntax here is following the runtime expression syntax of the Arazzo Specification. 

Field Name	Description	Required
stepId	Unique string to represent the step.	Yes
description	A description of the step.	No
operationId	A operationId defined within an API referenced in the sourceDescriptions.	conditional:  operationId or operationPath or workflowId must be defined
operationPath	A JSON Pointer reference to an API referenced within the sourceDescriptions (as operationId is not mandatory in OpenAPI we have to have other ways to reference operations L ).	conditional:  operationId or operationPath or workflowId must be defined
workflowId	A workflowId defined within an Arazzo workflow referenced in the sourceDescriptions (or another workflow in the current Arazzo doc).	conditional:  operationId or operationPath or workflowId must be defined
parameters	A list of parameters that  MUST  be passed to an operation or workflow referenced in this step	No
requestBody	The request body to pass to an operation if referenced.	No
successCriteria	A list of assertions to determine the success of the step.	No
onSuccess	An array of success action objects that specify what to do upon step success (maybe we can jump to the last step if certain conditions hold true).	No
onFailure	An array of failure action objects that specify what to do upon step failure (can we recover and retry or call another workflow first etc.).	No
outputs	These are things to return from the step and can processed subsequent steps in the workflow or mapped to workflow outputs.	No

Arazzo Structure – Step Parameters 

When defining an Arazzo step that will call an API, it’s normal that you may have to specify certain parameters on the operation. These could be HTTP headers, query parameters, path parameters etc. Arazzo caters for this via the Parameters Object. 

Figure 9 - Arazzo Specification - Step Parameters Example 

In the example above, four query parameters are defined. The values for the first three parameters are dynamic and mapped from properties defined in the inputs. The status property value is a literal string (e.g. “available”). 

Field Name	Description	Required
name	The name of the parameter.	Yes
in	The location of the parameter. Possible values are "path", "query", "header", or "cookie". When the step in context specifies a  workflowId, then all parameters map to workflow inputs.	conditional: required if operationId or operationPath are specified in the step.
value	The value to pass in the parameter. The value can be a constant or a Runtime Expression.	Yes

Arazzo Structure – Step Success Criteria 

To decide on what to do once a step completes, we need to know if the step is successful or not. This could be a simple check, or it could be more complex like checking the HTTP Status Code returned by an API call as well as inspecting certain contents in the response payload. The successCriteria specifies the list of conditions to be verified. If all the specified assertions pass, then a step can be deemed successful. 

Figure 10 - Arazzo Specification - Step Success Criteria Example 

In the example above, two criteria are specified. Both must evaluate to true for the step to be deemed successful. The first condition specifies that the HTTP status code returned from the API call must be 200. The second condition specifies that the response from the API must contain a response body, which is expected to be of type application/json, and that within the payload there will be a root level pets array - the length of which should be greater than zero. 

Field Name	Description	Required
context	A Runtime Expression used to set the context for the condition to be applied on.	conditional:   If type is specified, then the context  MUST  be provided
condition	The condition to apply. Conditions can be simple (e.g. $statusCode == 200 which applies an operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex or JSONPath, the type and context  MUST  be specified.	Yes
type	The type of condition to be applied. If specified, the options allowed are  simple, regex, jsonpath  or  xpath.

Arazzo Structure – Failure Action Object 

As is life, API calls do not always go as we expect. Being able to deal with the non-happy path, is a particular strength of the Arazzo Specification. The onFailure property within a step lets us to specify what should be done if an API returns something that does not meet the conditions defined within the successCriteria property. If none are specified, then the overall workflow will stop at the point of failure. 

Figure 11 - Arazzo Specification - Failure Action Example 

The example above specifies a retry type of failure action which will be executed if the API referenced by the step returns an HTTP Status Code of 503 (e.g. server unavailable). Based on the configuration, the current step should be retried after 1 second (as specified by the retryAfter), and if the API continues to return a 503-status code, we should stop the retries after 5 attempts (as specified by the retryLimit). 

Field Name	Description	Required
name	The name of the failure action.	Yes
type	The type of action to take. Possible values are "end", "retry", or "goto".	Yes
workflowId	The workflowId referencing an existing workflow to transfer to upon failure of the step.   This field is only relevant when the type field value is "goto" or "retry". A common example would be if an API returned a HTTP 401 due to an expired token, you could reference a refresh token workflow here.	No
stepId	The stepId to transfer to upon failure of the step. This field is only relevant when the type field value is "goto" or "retry".	No
retryAfter	The number of seconds to delay after the step failure before another attempt is to be made.
retryLimit	An integer indicating how many attempts to retry the step  MAY  be attempted before failing the overall step.	No
criteria	A list of assertions to determine if this action  SHALL  be executed.	No

There are three possible values for the type field. 

• end - The workflow ends, and context returns to the caller with applicable outputs. 
• retry - The current step will be retried. The retry can be constrained by the retryAfter and retryLimit fields.  
• goto - A one-way transfer of workflow control to the specified label (either a  workflowId  or  stepId). 

Arazzo Structure – Success Action Object 

By default, the steps specified within a workflow will execute in sequential order. In certain situations, we may be able to determine that we have the information required to be able to skip several steps and speed up the execution, letting us reap the value on offer faster! The onSuccess property enables this type of control. 

Figure 12 - Arazzo Specification - Success Action Object 

In the example above, we have a goto type success action. What the example demonstrates is that if we get back at least one pet matching the criteria in the request to the API, then we can jump to the joinWaitingList step. 

Field Name	Description	Required
name	The name of the success action.	Yes
type	The type of action to take. Possible values are "end" or "goto".	Yes
stepId	The stepId to transfer to upon success of the step. This field is only relevant when the type field value is "goto".	No
criteria	A list of assertions to determine if this action  SHALL  be executed.	No

There are two possible values for the type field. 

• end - The workflow ends, and context returns to the caller with applicable outputs. 
• goto - A one-way transfer of workflow control to the specified label (either a  workflowId  or  stepId). 

Arazzo Structure – Step Outputs 

When we execute a workflow step, we often want to make information available to subsequent steps within the workflow. For example, if we searched for a product, then we might want to make the identifier of that product available for the next step to add it to our shopping basket. The step outputs are array contains a map between a single name and a dynamic output value.  

Figure 13 - Arazzo Specification - Step Outputs Example 

In the simple example above, we return an output with a unique name of petId, and its value is defined by a runtime expression which will be evaluated by the software processing the step to make the actual identifier of the pet available for subsequent steps in the workflow. 

Arazzo Structure – Workflow Outputs 

Workflow outputs follow the very same principal as those within a step. The only difference is that from a processing perspective, workflow outputs are returned to the calling context. If a software application was executing a workflow, then the outputs would be returned to the application for evaluation, storage, or rendering. 

Figure 14 - Arazzo Specification - Workflow Outputs Example 

Figure 15 - Other Reusable Objects within Arazzo 

Example 

Let’s run through a simple fictitious example of how a company can take advantage of the Arazzo Specification to enhance their API products and capabilities for consumers. To do so, we’ll assume the identity of a fictional company called PetCo. 

Problem Statement: 

We’ve identified a business problem. We’re being overwhelmed by the number of pets being abandoned at our pet store. 

Proposed Solution: 

Following extensive research, we’ve decided to create the capabilities to search for and adopt pets that we catalog. We’ll offer this adoption service through our website and make the APIs available with wider eco-system of pet shelters, pet charities, and pet orphanages who expressed a need for such a service in our research. 

Our APIs: 

Based on our organization structure, we have set up a new team who will manage the adoption APIs and they are separate to the core Pets catalog facility. Thus, APIs we have on offer are as follows: 

1. Pets API – offering resources and methods required for cataloging pets. 
2. Adoptions API – offering resources and methods to initiate and manage adoptions. 

Figure 16 - Example Pets API 

Figure 17 - Example Adoptions API 

The Workflow 

To streamline the understanding and consumption for the wider eco-system of consumers, we want to articulate the process involved in adopting a pet that matches certain criteria. To do so, we’ll leverage the Arazzo Specification to describe the following required steps. 

1. Search for a pet based on certain criteria. 
2. Initiate an adoption request. 
3. Confirm adoption by updating the adoption status. 
4. Verify the adoption has been completed by ensuring the pet catalog entry no longer has the pet tagged as available. 

In the video below, we showcase how we can leverage our public Arazzo Specification GPT to fast-track the creation of the Arazzo Document, and to prepare our API Hub Developer Portal with the ‘Adopt Pet’ product including step-by-step developer documentation and client code samples. 

Figure 18 - Arazzo Specification GPT by SmartBear

Conclusion 

The Arazzo Specification is poised to play an important role in the future of API technology. With a rising demand for sophisticated APIs that interconnect across many digital ecosystems, the specification will need to handle intricate scenarios, accommodate emerging technologies (like AI). In fact, the shift towards AI-driven API consumption is accelerating the need for deterministic API workflows!  

Whether you're automating workflows, enabling AI consumption, or enhancing API governance, Arazzo is the key to unlocking the next generation of API-driven innovation. By being an open standard within the OpenAPI Initiative under the Linux Foundation, Arazzo is positioned to evolve in an open and collaborative manner and continue supporting the needs of the industry. 

There’s a vibrant tooling eco-system emerging with support for Arazzo and we’re busy working on broad support for Arazzo across our API Hub offering at SmartBear. If you can’t wait for us to drop that, you should check out Spectral for linting Arazzo documents, and play with our Arazzo GPT in the OpenAI GPT store.