The Arazzo Specification 1.1 moves API workflow descriptions closer to the way modern systems actually behave. API workflows are rarely a single request followed by a single response. They often involve several APIs, events, retries, shared data, and rules for deciding whether a workflow should continue.

Right from the beginning, Arazzo gave teams a standard way to describe multi-step API workflows. Version 1.1 expands that model so workflows can cross more boundaries, compose more cleanly, and extract data more precisely.

The largest change in Arazzo 1.1 is support for AsyncAPI descriptions.

In Arazzo 1.0, workflows were centered on OpenAPI-described HTTP operations. Developers could use Arazzo to describe workflows and run end-to-end or contract tests for synchronous APIs. However, many real-life workflows also include asynchronous behavior: publish an event, wait for a message, correlate a response, or continue only after another system acknowledges the work.

Arazzo 1.1 allows sourceDescriptions to reference AsyncAPI documents in addition to OpenAPI and Arazzo documents. Steps can then use AsyncAPI operations or channels, and each asynchronous step declares whether it sends or receives a message.

sourceDescriptions:
  - name: CafeNotifications
    url: ./cafe-notifications.asyncapi.yaml
    type: asyncapi

An async step example::

- stepId: placeOrder
  operationId: $sourceDescriptions.CafeNotifications.placeOrder
  action: send
  parameters:
    - name: requestId
      in: header
      value: $inputs.correlationId
  requestBody:
    payload:
      productId: $inputs.productDetails.productId

- stepId: confirmOrder
  operationId: $sourceDescriptions.CafeNotifications.confirmOrder
  action: receive
  correlationId: $inputs.correlationId
  timeout: 6000
  outputs:
    orderId: $message.payload.orderId

This makes it possible to describe a workflow that starts with an HTTP request, publishes to an event bus, waits for a response message, and then uses that response in a later step.

Two additions make these event-driven workflows easier to reason about:

• correlationId connects an outgoing message with the incoming message the workflow is waiting for.
• timeout defines how long the step should wait before it fails.

The new dependsOn field also lets a step declare which steps must finish before it can run. Use dependsOn when writing workflows that aren't purely linear, or when several steps prepare data before another step can continue.

Arazzo 1.1 improves workflow composition by allowing Action Objects to call another workflow and pass inputs with the parameters field. These new reuse capabilities are especially useful for shared behavior.

For example, many workflows need the same token refresh sequence, the same setup step, or the same cleanup step. Instead of repeating that logic in every workflow, Arazzo descriptions can point to a reusable workflow and map the values it needs.

name: renewSessionAfterUnauthorized
type: retry
workflowId: renewCustomerSession
parameters:
  - name: sessionRenewalToken
    value: $inputs.sessionRenewalToken

In this example, the values under parameters are passed as inputs to the renewCustomerSession workflow. The sessionRenewalToken becomes an input value available inside that called workflow.

As a result, your workflow files are smaller and have a cleaner separation between the business workflow and the support workflows around it.

Arazzo workflows often depend on data produced earlier in the sequence. A response body might contain the user ID needed in the next request, or a message payload might contain the status that decides whether a workflow succeeded.

Version 1.1 introduces the Selector Object for more precise data extraction. Selectors can use jsonpath, xpath, or jsonpointer, with a context that defines where selection starts.

outputs:
  orderConfirmationCode:
    context: $response.body
    selector: $.order.confirmation.code
    type: jsonpath

Selectors are available in several places where workflows map or reuse data, including: workflow outputs, step outputs, request bodies, parameters, and payload replacement values.

Arazzo 1.1 also refines expression typing. The Expression Type Object can now identify both the expression language and version. WIth this feature, teams can assure predictable behavior across tooling, especially when different versions of JSONPath or XPath may interpret expressions differently.

OpenAPI 3.2 added support for describing an entire query string as a value. Arazzo 1.1 aligns with that model by adding querystring as an option for the Parameter Object in field. As a consequence, workflows can pass complex query structures as one mapped value instead of modeling every individual query parameter.

- name: searchParams
  in: querystring
  value: "sort=desc&limit=10"

Use this option for search, filtering, and other operations where the query string can be dynamic or composed from several workflow inputs.

Arazzo descriptions can now define a root-level $self URI. When another Arazzo document references that description by URI, implementations use $self as the document identity if it is present.

arazzo: 1.1.0
$self: https://api.example.com/workflows/cafe-ordering.arazzo.yaml
info:
  title: A cafe ordering workflow
  version: 1.0.0

This helps avoid ambiguity when workflows are split across files, moved between environments, or resolved through different URLs. For larger API programs, stable identity is important because workflow reuse only works well when references are predictable.

Arazzo 1.1 adds clarification in a few areas that matter for tool builders and workflow authors: clarified grammar for runtime expressions, defined ordering for resolving Source Description Objects, explicitly describe truthy and falsy success criteria evaluation semantics. These details reduce guesswork. They also make it easier for editors, linters, validators, generators, and workflow execution tools to agree on how an Arazzo description file should behave.

Arazzo 1.1 keeps the specification focused on its core purpose: describing how APIs work together to complete a task.

To learn more, visit the what is Arazzo or read the Arazzo specification 1.1.

Are you using Respect, or would AsyncAPI support help your workflows? Let us know about your experience with Respect and whether you want us to support AsyncAPI.