Wiki · Concept · Last reviewed June 25, 2026

Arazzo Specification

The Arazzo Specification is an OpenAPI Initiative standard for describing multi-step API workflows: not just what endpoints exist, but how calls depend on one another to achieve a defined outcome.

Category: Concept / API Workflows Updated: June 25, 2026 Tags: Arazzo, OpenAPI, AsyncAPI, agents, workflow governance

Definition

The Arazzo Specification is a community-driven OpenAPI Initiative specification for expressing sequences of API calls and the dependencies between them. The current published version is Arazzo v1.1.0, dated May 17, 2026. Where the OpenAPI Specification describes HTTP API operations, Arazzo describes workflows that use API descriptions to reach an outcome: authenticate, select a resource, submit an order, wait for confirmation, recover from failure, or return a final output.

The specification is useful because real API use is often procedural. A single endpoint rarely tells a caller how to complete a task. The missing knowledge lives in tutorials, sample code, support answers, and institutional memory. Arazzo turns some of that tacit sequence knowledge into a document that can be reviewed, linted, tested, and used by human developers, software tools, and agent hosts.

Mechanism

An Arazzo Description is a JSON object that may be represented in JSON or YAML. The required top-level elements include the arazzo version field, an info object, at least one sourceDescriptions entry, and at least one workflow in the workflows field. Source descriptions point to the API or workflow descriptions that the Arazzo document relies on. In v1.1.0, the OpenAPI Initiative highlights AsyncAPI support, so workflows can coordinate both synchronous HTTP operations and event-driven interactions described by AsyncAPI.

A Workflow Object describes steps across one or more APIs. It can define inputs, ordered steps, dependencies on other workflows, workflow-level parameters, success actions, failure actions, and outputs. A Step Object can call an operation by operationId, reference an operation or event channel by path, or invoke another workflow. Steps can pass parameters and request bodies, define successCriteria, map outputs for later steps, set timeouts, and declare asynchronous send or receive intent through the action field.

The specification also defines runtime expressions for passing values from inputs, prior step outputs, workflow outputs, source descriptions, or reusable components. That is the practical bridge between "first get the session token" and "then place it in the next request header." Arazzo is not a script runner by itself; it is a structured workflow description that implementations can interpret.

Agent Context

For AI agents, Arazzo fills a gap between endpoint discovery and reliable task execution. An agent given only a large OpenAPI file may infer the wrong call order, skip a prerequisite, mishandle pagination, or treat an optional-looking field as irrelevant when it is required by business process. An Arazzo workflow can narrow the action path: this input, these calls, these dependencies, these success conditions, these failure branches, these outputs.

That makes Arazzo adjacent to Tool Use and Function Calling, Model Context Protocol, and API-based Agentic Commerce. A platform could expose one workflow as an agent tool instead of exposing every low-level endpoint. The benefit is not autonomy. The benefit is less improvisation at the interface boundary.

Governance Use

Arazzo gives governance teams a concrete artifact to review before an agent or automation system performs a multi-step task. A review can ask whether the referenced source descriptions are current, whether the workflow uses least-privilege credentials, whether success criteria are strong enough, whether failure actions retry safely, whether outputs leak sensitive data, and whether human approval is required before irreversible steps.

The OpenAPI Initiative lists use cases including living workflow documentation, documentation generation, MCP and SDK generation, test automation, compliance checks, predictable agent execution, and orchestration across HTTP and event-driven APIs. In governance terms, those are different risk surfaces. A documentation-only workflow may be harmless; an executable refund, purchase, deletion, or account-change workflow needs stronger evidence and controls.

Limits

Arazzo does not enforce a security mechanism. The specification leaves security to implementers and warns that processing an Arazzo Description can cause safe or unsafe operations to be performed on network resources. A workflow document can be syntactically valid and still be dangerous, stale, overbroad, or malicious.

It also does not prove that the underlying APIs behave as described. A workflow can reference an outdated OpenAPI description, depend on undocumented side effects, omit rate limits, or encode an unsafe retry pattern. For agents, the danger is that a clean workflow may feel more authorized than it is. The document should guide execution, not replace authorization, testing, incident planning, or human accountability.

Review Record

Source Discipline

Claims about Arazzo should cite the exact specification version, not just the OpenAPI brand. The publications page should be checked for the latest published version and schema iteration. Claims about workflow structure, required fields, runtime expressions, security limits, and media types should cite the specification. Claims about AI-agent use cases should be tied to OpenAPI Initiative materials and treated as design rationale, not proof of safety.

Spiralist Reading

Spiralism reads Arazzo as choreography before agency. The workflow says: here is the intended path, here are the pauses, here is what counts as success, here is what happens on failure. That is a healthier posture than letting a model invent ritual from endpoints. But the choreography still needs a steward. A ritual can be precise and still be wrong.

Sources

Return to Wiki