So while building the UseArazzo toolkit, I couldn’t rely on a rough sense of how the specification has evolved. I needed the exact diff. I downloaded the three spec texts, diffed them line by line, cross-checked every hunk against the release notes and the pull requests behind it, and kept notes as I went, because the Validator has to draw the line per version and the Runner has to honour it.
Those notes, tidied up, are this article. It’s for anyone who has to care what the arazzo: line at the top of a document means: people writing the documents, and people writing the tools that read them. If yours still say arazzo: 1.0.0, here is what changed since, what you need to do about it, and what you’re now allowed to say that you couldn’t before.
| Version | Released | Nature |
|---|---|---|
| 1.0.0 | September 2024 | Initial stable release |
| 1.0.1 | January 2025 | Patch: erratum fixes and clarifications, plus the first official JSON Schema |
| 1.1.0 | May 2026 | Minor: AsyncAPI v3 sources, Selector Objects, step dependencies, document identity, tightened evaluation semantics |
The short version: 1.0.1 removed three things that never worked and fixed the examples. 1.1.0 added a lot and, on paper, broke nothing. The rest of the post is the long version.
1.0.1 adds no objects, no fields, and no enum values. Every change is an erratum fix or a clarification. A patch release isn’t allowed to break anything, and this one doesn’t in the versioning sense: what it removes never worked. But if a document relied on one of those leftovers, removal feels like breakage, so those come first.
$message removed from the runtime expression grammar. AsyncAPI support was dropped before 1.0.0 shipped, but $message. survived in the ABNF: grammatically legal, resolving to nothing. 1.0.1 removes it. It returns in 1.1.0 with real semantics.in: body removed from the Parameter Object. Request bodies are expressed through the step’s requestBody, so in: body had no defined meaning. in is now path, query, header, or cookie.workflowId references into an external arazzo source always need the runtime expression form. 1.0.0 required $sourceDescriptions.<name>.<workflowId> only when multiple arazzo source descriptions existed. 1.0.1 requires it whenever the referenced workflow lives in an arazzo source description at all. Local workflows still use the bare workflowId. Applies to the Step, Success Action, and Failure Action Objects. Strictly a clarification, but it’s the one that can make a previously accepted document fail a linter.$steps.<stepId>.outputs.<name>. The 1.0.0 grammar always said .outputs., but the spec’s own example wrote $steps.getPetStep.availablePets without it, and people copied the example. Any parser that accepted the short form was matching a spec bug. If your documents use it, they were never valid; fix them whichever version you target.retryAfter applies only to type: retry. 1.0.0 also mentioned type: function, which never existed (the allowed types are end, retry, and goto).$steps.someStepId.outputs.pets#/0/id and $workflows.foo.outputs.mappedResponse#/name, and the “Workflow output value” note now describes payload fragments the same way step outputs do.1.1.0 is where the specification grew. It removes no fields, no enum values, and no expression roots. Bump the version string and a 1.0.1 document is a 1.1.0 document. The categories below are ordered by how likely they are to matter to an existing document.
A minor release can’t break existing documents, and 1.1.0 removes nothing. Two things can still change how an existing document behaves, because they define what 1.0 left to the implementation:
null or string case may now give a different answer. The condition grammar itself is still unspecified, so not every guess went away.steps array, and the workflow doesn’t use dependsOn, implementations should now reject it.type: asyncapi joins openapi and arazzo, and the Step Object gains the fields to talk to an event channel:
channelPath: a source description plus a JSON Pointer to a channel, for AsyncAPI operations that have no operationId. Mutually exclusive with operationId and workflowId. When the operation does have an operationId, the spec says to reference it that way instead, the same rule as operationPath for OpenAPI sources.action: send or receive.correlationId: for receive steps, which message to wait for. Must match the correlation ID in the AsyncAPI document.timeout: milliseconds to wait.A send step completes when the message is sent; Arazzo doesn’t model broker acknowledgment. A receive step completes when a matching message arrives within the timeout, or fails and triggers onFailure. With no successCriteria, any matching message is success. The spec’s own example, trimmed:
- stepId: confirmOrder
operationId: $sourceDescriptions.asyncOrderApi.confirmOrder
action: receive
correlationId: $inputs.correlationId
dependsOn:
- placeOrder
timeout: 6000
outputs:
orderId: $message.payload.orderId
Scope note: 1.1.0 supports AsyncAPI v3 only. The final text links to the v3 Operations Object, send/receive is v3 terminology, and the only example is asyncapi: 3.0.0. Nothing addresses v2.
Selector Object. Apply JSONPath, XPath, or JSON Pointer to structured data instead of reaching for a runtime expression with a pointer suffix. context is a runtime expression that must evaluate to structured data, selector is the expression, type is jsonpath, xpath, jsonpointer, or an Expression Type Object:
outputs:
firstPetId:
context: $response.body
selector: $[0].id
type: jsonpath
Allowed anywhere a value used to be just a runtime expression: workflow outputs, step outputs, a parameter’s value, a request body’s payload (nested at any depth), and a Payload Replacement’s value. This is the addition I expect to see in the most documents.
dependsOn. A list of stepIds that must complete before this step runs. Cross-workflow: $workflows.<workflowId>.steps.<stepId>. Cross-document: $sourceDescriptions.<name>.<workflowId>.steps.<stepId>. Intended as a join point for in-flight async work; for purely synchronous workflows the recommendation is still to order the array and not use it.parameters on Success Action and Failure Action Objects. An action with a workflowId can now hand inputs to the workflow it starts. in must not be used on them.$self on the Arazzo Object. A URI reference that is the document’s canonical identity and the base URI for its relative references. Must not contain a fragment; may itself be relative, resolved against the retrieval URI. If you know JSON Schema, $self is to an Arazzo document what $id is to a schema resource.$message and $self as runtime expression roots. $message sources are header., query., path., body, and payload.type gains jsonpointer; version gains rfc9535 (JSONPath), xpath-31 (XPath 3.1), and rfc6901 (JSON Pointer), which are now the explicit defaults.target may be a JSONPath as well as a JSON Pointer or XPath, and the new targetSelectorType says which. Defaults: JSON Pointer for application/json, XPath for XML media types. value accepts a Selector Object.in gains querystring (the OpenAPI 3.2 concept where the whole query string is one pre-formatted value); value accepts a Selector Object; in may be omitted whenever the step, success action, or failure action in context targets a workflowId.outputs accept a Selector Object as well as a runtime expression.$inputs. and $outputs. formally allow a #json-pointer suffix; $components. covers successActions and failureActions alongside parameters; $sourceDescriptions.<name>.<x> gets a resolution order (operation or workflow ID first, then a Source Description field such as url or type); {...} embedding is formally defined, with serialization rules (scalars to strings, objects and arrays to JSON, strings as-is).regex, jsonpath, and xpath conditions, runtime expressions must be embedded as {$expr} and substituted before evaluation. Truthiness per type: a simple condition as written, a regex must match, a JSONPath must produce a non-empty nodelist, an XPath uses its effective boolean value. An evaluation error is a failed criterion. Multiple criteria are combined with logical AND. Simple conditions: null equals only null, numeric strings coerce to numbers, string comparison is case-insensitive. What 1.1.0 still doesn’t provide is a grammar for simple conditions: the operators are listed, but tokenization and precedence are left to the implementation, unlike runtime expressions, which get a full ABNF. I wrote about one 1.0 condition no tool could evaluate safely for exactly this reason; that article proposes a grammar and evaluation semantics, and adding them to the specification is proposed in #518 and #517.successCriteria, if present, must contain at least one Criterion Object.retryAfter is no longer required when type: retry, and a retry failure action no longer has to name a stepId or workflowId. Both bring the schema in line with what the prose always allowed. The 1.1 schema is a separate iteration, 2026-04-15.$steps.stepId.outputs.field are implicit dependencies and tools must satisfy them; tools must also respect every declared dependsOn.$self if it has one, and absolute source urls resolve by identity, not location, so a document already loaded under its $self isn’t fetched again.$self, then the encapsulating entity, then the retrieval URI, then an application default. New Appendix B walks through examples. Relative references in API URLs resolve against the OpenAPI Server Object, not the Arazzo base URI.$steps. is step-id ".outputs." output-name ["#" json-pointer], $workflows. likewise, plus a strict identifier form without dots.$steps.loginUser to $steps.loginStep, "{$statusCode == 401}" to "$statusCode == 401", JSONPath examples updated to RFC 9535.Moving a document from 1.0.0 to 1.0.1:
arazzo: 1.0.0 to arazzo: 1.0.1.$message. and remove it; there was nothing for it to resolve against.in: body and move that data into the step’s requestBody.$steps. references missing .outputs. and add it. These were never valid.workflowId points into an external arazzo source description, write it as $sourceDescriptions.<name>.<workflowId>, even if there’s only one such source.Moving from 1.0.1 to 1.1.0:
successCriteria, re-read them against the new condition semantics, especially anything comparing to null or relying on case.parameters on actions, $self on multi-document setups, and AsyncAPI v3 sources with dependsOn for the join points.The 1.1.0 release is three months old, and most of the documents I’ve come across still say 1.0.1. That makes now a good time to read the changes, before habits form around the old ones.
I had a rough picture from working on the specification and on tooling, but a rough picture isn’t a list. So I went looking properly: the OAI repository, vendor blogs, YouTube, GitHub search, Slack threads, package registries, the odd LinkedIn post. I wanted to know what tools there were, who was writing about the spec, who was talking about it, and whether anyone had published a real Arazzo document for a real API.
It took longer than I expected, because nothing was in one place. That’s the normal state of a two-year-old specification, and it’s also the reason I kept notes. Those notes became the Arazzo Ecosystem page.
More than I thought, in some places. The page currently lists 24 tools from roughly 16 vendors and independent developers, covering authoring, validation, execution, generation from OpenAPI, and libraries in TypeScript, Python, Go, Java, and PHP. The specification itself is there in all three versions, with its JSON Schemas, official examples, and the places where its development happens.
Articles and talks are a different story: there’s far more out there than fits in a couple of evenings. The eleven articles and four videos listed so far are simply the ones I’ve read or watched myself, and I’d rather list fewer with an accurate one-line description than paste in a hundred links I haven’t opened. That section will grow steadily.
What I genuinely found little of: Arazzo documents published by API providers describing their own APIs, and anything yet on 1.1, which shipped in May with AsyncAPI support.
I’ve kept my opinions off the page on purpose. Each entry gets a one-line description of what it is, not a rating. The tools are grouped by the job they do, so you can find a runner or a linter without knowing vendor names first.
UseArazzo’s own toolkit. The page is for everyone else’s work, including tools that do the same jobs ours do. A registry that left those out wouldn’t be a reference, it would be a brochure, and the Arazzo ecosystem is far too young for that to help anyone. The only competition that matters right now is with “nobody uses this.”
The curation policy is written at the bottom of the page and it’s short: about Arazzo, reachable at a stable URL, not a duplicate. Any vendor, no ranking, free.
This is a first pass. I’ll keep adding things as I find them, and I’ll review the page regularly; the date is shown at the top so you can see how fresh it is.
But I’d rather not be the only one looking. If you’ve built something, written something, recorded something, or published an Arazzo document and it isn’t listed, submit it. The form takes a minute. If something listed is wrong or gone, tell me that too.
If you want to know when the page changes, there’s a commit feed for now and a newsletter on the way.
The ecosystem is bigger than it looks from any single corner of it. Now there’s a place to see the whole thing.
]]>A single API call is a solved problem: OpenAPI describes it, generators wrap it, every HTTP client on earth can make it. But the order you call the endpoints in, what you carry from one response into the next request, and how you know you’re done? That’s been improvised. Scripts, tribal knowledge, agents winging it at runtime. If you maintain an API, test one, or build agents on top of one, you’ve written that glue yourself.
Improvisation is exactly what you don’t want in production. That glue is rarely reviewed, rarely versioned alongside the API it drives, and it breaks quietly when the API changes.
If you haven’t met it yet: Arazzo is the OpenAPI Initiative’s specification for multi-step API workflows, authored by Frank Kilcommins, and it fixes that on paper. Where OpenAPI answers “what can I call?”, Arazzo answers “in what order, with what, and until when?”. A workflow document lists its source descriptions (usually OpenAPI documents), then a set of workflows made of steps. Each step points at an operation, says which parameters and body to send, declares what counts as success, and names the outputs it makes available to later steps.
A minimal document looks like this:
arazzo: 1.0.1
info:
title: Place an order
description: Look a product up by SKU, then order it.
version: 1.0.0
sourceDescriptions:
- name: shop
url: ./openapi.yaml
type: openapi
workflows:
- workflowId: placeOrder
description: Two calls, in order, with the product id carried between them.
inputs:
type: object
properties:
sku:
type: string
steps:
- stepId: findProduct
description: Resolve the SKU to a product id.
operationId: getProduct
parameters:
- name: sku
in: path
value: $inputs.sku
successCriteria:
- condition: $statusCode == 200
outputs:
productId: $response.body#/id
- stepId: createOrder
description: Order the product found in the previous step.
operationId: createOrder
requestBody:
contentType: application/json
payload:
productId: $steps.findProduct.outputs.productId
successCriteria:
- condition: $statusCode == 201
outputs:
orderId: $response.body#/id
outputs:
orderId: $steps.createOrder.outputs.orderId
Nothing here is code. It’s a plain document you can check into the repository next to the OpenAPI description it depends on, review in a pull request, and hand to any tool that understands the specification. If you stop using one toolkit, the workflow keeps working with the next one.
And here is what comes back when you run it. Hand the document and its inputs to the Runner (more on it below) and instead of a script that just ran, you get a record of the run:
const result = await executor.execute('placeOrder', { inputs: { sku: 'AZ-1001' } });
result.status; // 'completed'
result.outputs; // { orderId: 'ord_8f2c' }
result.steps;
// [
// { stepId: 'findProduct', successful: true, action: undefined, attempts: 1, durationMs: 142 },
// { stepId: 'createOrder', successful: true, action: undefined, attempts: 1, durationMs: 208 },
// ]
Each step in run order: whether it succeeded, which success or failure action was selected, how many attempts it took, and how long. When the second call fails at 2 a.m., that’s the difference between reading a trace and reading someone’s shell script.
Tooling for Arazzo exists. But it’s scattered across the ecosystem: a validator in one project, execution in another, nothing sharing an engine or a set of conventions. Each tool has to parse the document and resolve references its own way, so they can disagree on the edge cases.
So that’s the mission with UseArazzo: concentrate quality Arazzo tooling in one place, all of it sharing one engine. We’re starting with the three pieces everything else depends on.
Underneath them sit @usearazzo/parser and @usearazzo/resolver, the lower-level packages the products are built from, for people building their own Arazzo tooling. That shared engine is the point. When the Validator and the Runner disagree about a document, that’s a bug, not a difference of opinion.
That engine is built on SpecLynx, our own API tooling foundation: the semantic parsing core, reference resolution, and standards discipline that came out of years of Swagger and OpenAPI work. Between the two of us, Francesco and I were core contributors to the Swagger open-source projects on both the JavaScript and the Java side, and we contribute to the OpenAPI, AsyncAPI, and Arazzo specifications themselves. The About page has the receipts. That’s why the toolkit handles malformed documents, external references, and specification edge cases from day one instead of learning them the hard way.
Three principles guide the work:
This is raw. Heavy development, pre-1.0, nothing published to npm yet, APIs changing under our feet. Everything lives in one monorepo, usearazzo/arazzo-toolkit, under Apache 2.0.
I’m announcing it anyway. Everything is built in the open, and I’d rather have you watching, questioning, and shaping it from day one than unveil a polished black box a year from now.
Today the toolkit validates and runs Arazzo 1.0.0 and 1.0.1 workflows against OpenAPI 2.0, 3.0.x, and 3.1.x source descriptions. Arazzo 1.1.0 runs partially and doesn’t validate yet, and AsyncAPI isn’t supported. The compatibility table on the homepage is where we keep that current, and every product page tells you exactly where that piece stands, including what doesn’t exist yet. No smoke, no mirrors.
None of this is built. It’s where the toolkit is going, written down so you can tell what exists from what doesn’t.
Next to the three products we want a Language Service, so any editor gets Arazzo validation, completion, and navigation, and an Editor and a VS Code extension built on it. We want GitHub Actions that annotate violations on the diff and render the run trace into the job summary. We want agents to be able to author, validate, and run workflows, through Agent Skills, a generic MCP Server over any document, and an MCP Compiler that turns one workflow into one typed tool. And we want Arazzo Transformers: explicit, versioned transformations for reshaping data between steps, declared as ordinary API calls the toolchain can validate.
We’ll write about each of these here as it moves from idea to code.
We’re early enough that your input actually shapes the thing.
]]>