June 23, 2026 • Sebastien Andreo

Arazzo is an OpenAPI Initiative specification for describing API workflows: ordered sequences of callsOpenAPI Initiative specification for describing API workflows: ordered sequences of calls, their dependencies, the inputs they require, the outputs they pass forward, and the success or failure logic needed to achieve a real outcome. It is best understood as complementary to OpenAPI, not as a replacement for it. OpenAPI describes the calls; Arazzo describes the journey, the compiler as presented it in the following article.

That distinction matters because real systems rarely deliver value through one isolated request. They deliver value through workflows: retrieve an order, extract the customer/payment account reference, validate the account, decide whether to proceed, and handle the result correctly. Those steps may span multiple APIs, but the business outcome depends on how they fit together.

In the previous article, I argued that endpoint-valid APIs can still fail real workflows. The order management service returns a customer/payment account reference. The billing service accepts a customer/payment account reference. Both contracts can look reasonable on their own, yet the workflow still breaks because the value produced by one service is not actually usable by the next, and the failure comes back as an unhelpful HTTP 500.

That example exposes a specific gap. OpenAPI can tell us what an individual call means: what endpoint exists, what parameters it takes, what schema it returns, and which response codes are possible. What it does not fully express is how multiple calls are supposed to work together as a usable business flow.

That is where Arazzo becomes interesting.

Arazzo should not be framed as a replacement for OpenAPI, and it certainly does not make weak APIs magically composable. But it is a promising emerging layer for describing workflow intent across APIs: the ordered steps, dependencies, data handoffs, and expected transitions that sit above any single operation. If OpenAPI describes the pieces, Arazzo helps describe how the pieces are meant to be used together.

OpenAPI describes operations; workflows need another layer

OpenAPI has been hugely valuable because it standardizes the contract of a single API operation. It gives producers and consumers a common description of requests, responses, authentication, and schemas. That is foundational, and nothing about workflow-level thinking reduces its importance.

But a workflow is not just a list of operations. It is a path with rules.

A caller may need to fetch a resource, extract one field, pass it to another service, branch based on a result, handle a known failure mode, and only then continue. Somewhere in that sequence there are assumptions about ordering, compatibility, and allowed next actions. Today, those assumptions are often scattered across code, wiki pages, integration playbooks, tribal knowledge, and test suites.

That is manageable when a few expert humans own the integration. It is much less manageable when you want broader reuse, faster validation, or agentic execution. In those cases, the landscape needs a clearer description of the workflow.

This is the opportunity Arazzo points toward. It gives teams a way to describe not just what each API does, but how a consumer is expected to move across them to achieve a goal.

At a high level, that means a workflow document can link to its source API descriptions through sourceDescriptions, define named workflows around an outcome, break those workflows into ordered steps, and capture the inputs, outputs, and decision rules that connect one step to the next. It can also describe successCriteria, onFailure paths, and runtime expressions for pulling values from earlier responses. That is enough structure to be concrete without turning the article into syntax commentary.

Revisit the order and billing example

Take the workflow from article 1. A client wants to validate whether an order can proceed.

A simplified path looks like this:

  1. Retrieve the order from the order management API.
  2. Extract the customer/payment account reference from the response.
  3. Call the billing API with that reference.
  4. Interpret the billing result.
  5. Continue, stop, or route the workflow based on that outcome.

In many organizations, this flow exists only implicitly. The APIs may be documented, but the workflow contract is not. The caller is expected to infer which field matters, whether it is safe to pass directly, what preconditions apply, and how to react if billing rejects or cannot resolve the reference. Kin Lane argues that our “API contract” must go beyond the OpenAPI and generated documentation, and include processes such as onboarding and access. He notes that simply publishing an API, OpenAPI, and docs “doesn’t mean very much” if the provider does not explain how consumers actually get on board and obtain access tokens or better understand the business intention behind the APIs.

That missing layer matters because the workflow contains semantics that are not owned by either API alone.

The important question is not only, “What does GET /orders/{id} return?” It is also, “Which value from that response is intended to drive the next billing step?” Not only, “What does billing validation accept?” but also, “Under what conditions is the order system’s reference considered valid input for billing validation?”

Those are workflow questions. They describe the relationship between operations.

What Arazzo clarifies

At a conceptual level, Arazzo is useful because it encourages teams to externalize several kinds of intent that often remain implicit.

First, it can describe step sequencing. Some calls are only valid after earlier calls succeed. Some steps are optional. Some flows branch based on results. A workflow description makes that ordering visible rather than assumed.

Second, it can describe data handoffs. In the order-and-billing case, that means declaring which output from the order call becomes input to the billing call. Even that seemingly small act is valuable, because it forces teams to confront whether the handoff is actually well-defined.

Third, it can describe dependencies and conditions. For example, a billing validation step may only make sense if the order is in a payable state, or if a customer/payment account reference is present, or if the customer type is supported. Those preconditions are often real but under-documented.

Fourth, it can describe expected outcomes and transitions. If billing says the account is valid, the next step may proceed. If billing says pending, the process may pause. If billing says unknown reference, the workflow may stop and require remediation. This matters because usable systems are not just about happy-path calls; they are about whether the next valid action is clear.

Put differently: OpenAPI is excellent at describing each move. Arazzo is promising because it helps describe the dance.

A lightweight Arazzo-style view of the workflow

Using the same order-management and billing scenario, an Arazzo-style workflow description would make several things clear that are otherwise easy to hand-wave away.

  • Source descriptions: this workflow depends on the order-management API description and the billing API description.
  • Workflow: validateOrderForBilling or a similarly outcome-oriented name.
  • Steps: retrieve the order, verify the order is in a billable state, extract the customer/payment account reference, call billing validation, then branch on the result.
  • Inputs and outputs: the order ID comes in as workflow input; the order response produces the specific customer/payment account reference consumed by billing; the billing response produces a validation outcome used by later logic.
  • Success and failure rules: proceed only if the order contains the required reference and billing returns a valid result; stop, retry, or route for remediation when the response indicates a known failure.

That sounds simple, but it changes what can be reviewed and validated. A team can now ask concrete questions before implementation or before release:

  1. Does the order step actually return the field the workflow expects?
  2. is that field the right identifier for billing, not just a similarly named one?
  3. Is billing validation only allowed when the order is in a payable state?
  4. If billing returns “unknown reference,” is the next action to stop the workflow rather than surface a generic 500?

None of that means Arazzo automatically repairs the mismatch. It does not harmonize identifiers or execute the flow by itself. What it does is make the intended handoff, gating conditions, and failure handling clear enough to validate.

Why this helps workflow validation

The immediate value is not standards theater. It is validation.

When workflow intent becomes explicit, teams can inspect whether a business flow is coherent before a consumer discovers the mismatch in production. In the order-and-billing example, a workflow description would make the handoff object impossible to ignore. It would raise the question early: is the reference emitted by order management truly compatible with what billing expects, and under which workflow conditions is it even valid to try?

If the answer is no, that is already progress. The problem moves from runtime surprise to design-time visibility.

This also improves testing. Many teams test APIs independently and maybe add a few integration tests later. A workflow description provides a more direct target for cross-service validation: not just whether each endpoint responds correctly, but whether the sequence, handoffs, branches, and failure semantics hold together as a usable path.

And it improves agent readiness for a simple reason: agents need clear paths more than humans do. A human integrator can fill in missing logic with judgment and institutional memory. An agent needs clearer structure about what step comes next, what value to carry forward, and what failures mean for the workflow.

That does not mean an agent will consume Arazzo directly tomorrow in every environment. Adoption will vary. Tooling will evolve. But the direction is still significant. The more of that workflow logic is expressed in machine-readable form, the easier it becomes to validate, automate, reason about, and eventually execute.

Position Arazzo next to OpenAPI, not instead of it

It is important to keep the layers straight.

OpenAPI remains the contract for individual API operations. Without high-quality OpenAPI descriptions, a workflow layer sits on a weak foundation. If request schemas are vague, errors are poorly modeled, or authentication requirements are inconsistent, the workflow description cannot repair that.

Arazzo is valuable precisely because it sits next to OpenAPI. It depends on good operation-level contracts and adds something different: the cross-operation narrative of how those contracts are intended to compose.

That distinction matters architecturally. Teams do not need to choose between endpoint description and workflow description. They need both, because they answer different questions.

OpenAPI answers: what does this call mean?

Arazzo helps answer: how are these calls meant to work together?

For organizations thinking about composability, that is a much more useful framing than declaring a new spec to be the answer to everything.

Limitations and cautions

This is also where restraint matters.

Arazzo does not fix bad API design. If one service emits unstable identifiers, another accepts ambiguous inputs, and both hide predictable errors behind generic 500s, documenting the workflow does not solve the underlying design defect. It only makes the defect more visible.

That is still useful, but it is not the same as remediation.

There are other limits too. A workflow description can become stale if it is not maintained alongside API changes. Teams may disagree on the canonical flow when multiple variants exist. Some business processes are dynamic enough that any single linear description only captures part of the reality. And as with any emerging standard, ecosystem maturity matters: the specification can be promising before organizational habits and tooling catch up.

So the practical posture should be measured. Use Arazzo as a way to surface and validate workflow intent, not as an excuse to ignore API quality fundamentals. If the underlying contracts are inconsistent, fix them. If the workflow is ambiguous, clarify it. If the error model is useless, improve it. And if a workflow needs execution, orchestration, or retries, remember that those capabilities belong to tooling and runtime platforms, not to the specification itself.

Arazzo is not a substitute for design discipline. It is a way to make that discipline more visible.

Where it fits

The most constructive way to think about Arazzo is as part of a broader API design toolchain.

OpenAPI describes operations. Testing verifies implementation behavior. Governance sets rules for consistency. A workflow specification layer adds a missing architectural asset: a machine-readable description of how business intent crosses service boundaries.

That is why it matters. The composability problem from article 1 was not really about a missing endpoint. It was about missing clarity around how endpoints were supposed to cooperate. Arazzo is promising because it gives teams a way to write that intent down in a form that can be reviewed, validated, and eventually operationalized.

That does not end the conversation. In some ways it begins a larger one: if workflow quality becomes more visible and more important, then API landscapes themselves start to look less like a collection of interfaces and more like a strategic execution surface.

That is the bridge to the next article. Once workflow intent is treated as a real architectural concern, the next question is no longer just whether a spec exists. It is whether leaders are willing to invest in an API landscape that is actually usable for the agentic era.

References