Arazzo is the specification that finally gives the API world a standard way to describe workflows — the multi-step sequences of API calls that actually accomplish meaningful business outcomes — and I think it’s one of the more important specifications to emerge from the OpenAPI Initiative in years. OpenAPI describes individual operations: here’s an endpoint, here’s what it expects, here’s what it returns. But real work almost never happens in a single call. To do something useful — onboard a customer, process a payment, fulfill an order — you call a sequence of operations in a particular order, passing data between them, handling the dependencies and the branching. That sequence is a workflow, and until Arazzo there was no standard, machine-readable way to describe it. Arazzo fills that gap, and in doing so it addresses something I’ve argued the API world has neglected for years: the gap between individual operations and the actual outcomes consumers are trying to achieve.
The core idea of Arazzo is describing the workflow as a first-class, machine-readable artifact, the way OpenAPI describes the operations. Arazzo lets you express a sequence of API calls — across one API or even multiple APIs — with the inputs, outputs, dependencies, and success criteria for each step, so that the whole workflow becomes a defined, shareable, executable thing. The JSON Schema for Arazzo, which I wrote about in 2024, is the foundational map for understanding the specification, available in both JSON and YAML the way OpenAPI is. This matters because it means workflows can now be governed, documented, tested, and tooled the same way individual API definitions can. The workflow stops being tribal knowledge locked in a developer’s head or buried in a tutorial and becomes a machine-readable contract that describes how to actually accomplish something with an API.
The business-alignment argument is why I care about Arazzo most, and it’s the dimension I’ve emphasized. I wrote in 2025 that we need more APIOps cycles, Arazzo, and OpenAPI Overlays — and got MCP and A2A instead — contrasting the specifications that address genuine business alignment with the ones driven more by hype. Arazzo is on the business-alignment side because workflows are where APIs connect to business outcomes. A business stakeholder doesn’t care about your individual endpoints; they care about whether the customer can be onboarded, whether the payment can be processed, whether the order can be fulfilled — and those are workflows. Arazzo gives you a way to describe and govern the sequences that deliver business value, which means it connects the technical API layer to the business outcomes the API exists to serve. This is exactly the kind of specification the API world needs more of: one that bridges the gap between technical operations and meaningful business results.
The healthcare case is where I’ve seen Arazzo’s value most concretely, and it illustrates the broader point. I wrote in 2024 about needing FHIR API Arazzo workflows to deliver real-world healthcare experiences — because the FHIR specification is enormously complex, full of individual resources and operations, and what healthcare actually needs is the workflows that string those resources together into meaningful clinical and administrative experiences. A patient accessing their records, a provider submitting a claim, a referral being processed — these are workflows across many FHIR operations, and Arazzo is how you describe them so they can be implemented consistently, tested, and understood. The FHIR example generalizes: any complex API domain has the same gap between its many operations and the workflows that make them useful, and Arazzo is the specification that closes that gap.
The relationship to the broader specification ecosystem is where Arazzo fits into a coherent picture, and I’ve mapped it carefully. Arazzo sits alongside OpenAPI, JSON Schema, OpenAPI Overlays, and APIs.json as part of the layered set of specifications that describe different aspects of API operations. OpenAPI describes the operations; Overlays apply targeted modifications and specialization; APIs.json indexes and discovers; and Arazzo describes the workflows that sequence the operations into outcomes. My conversation with Frank Kilcommins about the Arazzo specification, which I published in 2025, traced its history and its adoption for guided walkthroughs, SDK generation, and testing — because once you have a machine-readable workflow definition, you can generate a lot from it: documentation that walks users through the sequence, SDKs that implement the workflow, tests that verify it works end to end. Arazzo is a generative artifact the same way OpenAPI is, producing value across the lifecycle from a single source of truth.
Where Arazzo becomes genuinely important, and where my interest in it connects to my deepest long-running themes, is the agent era. I wrote in 2025 that where people see AI agents, I see API discovery, semantics, hypermedia, and workflows — and Arazzo is the workflows piece of that. An AI agent trying to accomplish a real task doesn’t just need to call individual operations; it needs to execute the right sequence of operations in the right order to achieve an outcome, which is exactly what a workflow is. Arazzo gives agents a machine-readable description of how to accomplish multi-step tasks with an API, which is precisely what the agentic era needs. The workflow specification that looked like a useful convenience for human developers turns out to be foundational infrastructure for machine consumers that need to execute complex sequences reliably. Arazzo is, in this light, part of the standardization work that prepares APIs for a world where the consumers are increasingly agents executing workflows rather than humans making individual calls. It’s a specification I expect to matter more over time, not less, because the gap it fills — between individual operations and meaningful outcomes — only becomes more important as the consumers become machines that need to accomplish real work, not just make isolated requests. Arazzo is the API world finally taking workflows seriously, and that’s a development I’ve wanted to see for a long time.
References
- APIs.json Workflows
- The JSON Schema For The Arazzo Specification
- We Need FHIR API Arazzo Workflows To Deliver The Real-World Healthcare Experiences
- API Evangelist Conversation With Frank Kilcommins About The OpenAPI Arazzo Specification
- You See AI Agents, But API Evangelist Just Sees API Discovery, Semantics, Hypermedia, And Workflows
- The Silence And Noise Of APIs.json, OpenAPI, JSON Schema, Arazzo, And Spectral Or Vacuum Rules
- We Need More APIOps Cycles, Arazzo, Overlays, And We Get MCP And A2A
