npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml
The validator post explained why the validator’s own command line went away (toolkit #7). The short version: one home for the command line, not one per package.
So the CLI is a thin layer. It parses flags, loads a configuration file, formats the diagnostics, and sets the exit code. Everything else is the validator’s validateURI. That means the CLI and the library can never disagree about a document. If a rule fires in one, it fires in the other.
Let me show you. Here is adopt-a-pet.arazzo.yaml from the validator post again. The two steps on lines 16 and 19 are both called find-pet:
arazzo: 1.0.1
info:
title: Adopt a pet
summary: Find a pet and adopt it.
description: Find an available pet in the store and adopt it.
version: 1.0.0
sourceDescriptions:
- name: petstore
url: ./petstore.openapi.json
type: openapi
workflows:
- workflowId: adopt-a-pet
summary: Adopt a pet.
description: Find an available pet and adopt it.
steps:
- stepId: find-pet
description: Find an available pet.
operationId: findPetsByStatus
- stepId: find-pet
description: Adopt the pet.
operationId: updatePet
Last time it took a script to find them. Now it takes one command:
$ npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml
adopt-a-pet.arazzo.yaml
16:9-18:38 error 9040403 Every step must have a unique 'stepId' within a workflow.
19:9-22:1 error 9040403 Every step must have a unique 'stepId' within a workflow.
✖ 2 problems (2 errors)
Quite simple. Notice that lines count from 1 here, not from 0. That’s the script’s + 1, done for you, so you can jump straight to the line in your editor. The number in the third column is the rule’s code, and the Validator API reference lists every one.
Prefer it installed? npm install --global @usearazzo/cli gives you a usearazzo binary. The argument can be a path, a file: URI, or an HTTP(S) URL.
From here, the place to go is the CLI reference. It covers every option, both output formats, the exit codes, and the configuration file.
Not the output. It reads the exit code. People wire a command into CI and stop looking at it, so the exit code has to mean exactly one thing, every time.
By default, only errors fail a run. A warning is advice, not a violation, so a document with warnings exits with 0. Take onboarding.arazzo.yaml, whose only problem is a step without a description. It passes. Want stricter? Lower the threshold:
$ npx @usearazzo/cli validate onboarding.arazzo.yaml --fail-severity warning
onboarding.arazzo.yaml
16:9-18:1 warning 9050201 Step 'description' should be present and non-empty string.
⚠ 1 problem (1 warning)
$ echo $?
1
Now, what if the report is long? A hundred problems clutter a CI log, so --max-problems caps the list. But we can see an obvious problem here. Picture a hundred warnings and one error at the very end. Show the first ten, and the error isn’t among them. Should the run pass? Of course not. So the exit code is computed from every problem, before the list is cut, and the output says how many were left out:
$ npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml --max-problems 1
adopt-a-pet.arazzo.yaml
16:9-18:38 error 9040403 Every step must have a unique 'stepId' within a workflow.
✖ 1 problem (1 error)
(showing 1 of 2 problems)
There’s one more trap, and it’s a quiet one. The obvious way to end a Node.js CLI is process.exit(). Well, it can cut your output short. When stdout is a pipe, writes are asynchronous, and exiting early drops whatever is still in the buffer, at around 64 KB. A big JSON report piped into another tool would arrive broken, with no error anywhere. So the CLI sets the exit code and lets the process end on its own. The test suite pipes more than 64 KB of JSON through it, to keep it that way.
No. A validator reads your files. It should never write over them.
-o writes the report to a file. Point it at the input document by mistake, and you’d replace your workflow with a list of its problems. So the CLI refuses:
$ npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml -o adopt-a-pet.arazzo.yaml
Error: --output path must differ from the input file
It’s important to realize that comparing path strings isn’t enough for that. A symlink, a hard link, or a case-insensitive file system can give the same file a different name. So the CLI also compares what the paths point at on disk.
The configuration file follows the same thinking. It holds your validation settings, and the CLI finds it in the working directory: .usearazzo.yaml, usearazzo.json, and a few spellings in between. It’s YAML or JSON only, and that’s deliberate.
Alpha means options and output can still move before 1.0. Concretely:
validate. It accepts the same versions as the rest of the toolkit: Arazzo 1.0.0, 1.0.1, and 1.1.0, in JSON and YAML.stylish is for people. --json prints Language Server Protocol diagnostics, exactly what the library returns, for other tools.1 when a problem at or above --fail-severity is found, or when the run can’t finish. 0 otherwise.--help and --version answer in about a tenth of a second. The validator is loaded only when a command needs it.The feedback I want most:
Discussions is the place, and the monorepo is where the issues go.
Two things matter most to me for the CLI itself.
The first is custom rules. The built-in rules check what the Arazzo specification says. But every team has conventions of its own: how a stepId is named, which fields a workflow must carry, which source descriptions are allowed. Those belong in the same run, with the same output and the same exit code. The catch is that a rule is code, and a YAML configuration file can only carry data. Rules would arrive through JavaScript configuration files. Loading one means running code from whatever directory you validate, so that’s deferred on purpose until it has a careful design (toolkit #219).
The second is more output formats. Today there are two: stylish for people, and json for other tools. The validator’s old command line also had a codeframe format, which prints the offending lines of the document under each problem, and a github-actions format, which turns each problem into an annotation on the pull request diff (toolkit #7). They didn’t make the first release of the CLI, and I’d like them back.
Beyond validation, the CLI will grow commands for the rest of the toolkit (toolkit #84). run-workflow and run-operation arrive when the Runner is published, and the CLI page describes the rest.
Which of these would you use first? Nothing here is built yet, so this is the cheapest moment to change it.
Validating an Arazzo document in CI is now one line in your workflow file. No script, no glue. Sounds pretty easy, right? Give it a try, and let me know in Discussions which flag you missed.
]]>npm install @usearazzo/validator
This post is about one idea. When the validator reports nothing, your document has to be fine. Most of the work before publishing went into making that true.
Let me show you the simplest use. Point it at a file, keep the errors, and fail when there are any:
import { validateURI, DiagnosticSeverity } from '@usearazzo/validator';
const diagnostics = await validateURI('./adopt-a-pet.arazzo.yaml');
const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);
for (const { range, message } of errors) {
console.log(`${range.start.line + 1}:${range.start.character + 1} ${message}`);
}
console.log(`${errors.length} errors`);
process.exitCode = errors.length > 0 ? 1 : 0;
Here is adopt-a-pet.arazzo.yaml. The two steps on lines 16 and 19 are both called find-pet:
arazzo: 1.0.1
info:
title: Adopt a pet
summary: Find a pet and adopt it.
description: Find an available pet in the store and adopt it.
version: 1.0.0
sourceDescriptions:
- name: petstore
url: ./petstore.openapi.json
type: openapi
workflows:
- workflowId: adopt-a-pet
summary: Adopt a pet.
description: Find an available pet and adopt it.
steps:
- stepId: find-pet
description: Find an available pet.
operationId: findPetsByStatus
- stepId: find-pet
description: Adopt the pet.
operationId: updatePet
Run the script, and it finds both:
16:9 Every step must have a unique 'stepId' within a workflow.
19:9 Every step must have a unique 'stepId' within a workflow.
2 errors
Why the + 1? Diagnostics count lines and characters from 0, the way editors do.
Already holding the text, say in an editor or a test? Then skip the file and use validate:
import { validate, createTextDocument } from '@usearazzo/validator';
const textDocument = createTextDocument('file:///home/you/adopt-a-pet.arazzo.yaml', yamlText);
const diagnostics = await validate(textDocument);
From there, the place to go is the Arazzo Validator API reference. It covers every function, option, and error, and all 251 rules, with each message quoted exactly as the validator reports it.
Each line the script printed is one diagnostic. Here is the first one in full:
{
"range": { "start": { "line": 15, "character": 8 }, "end": { "line": 17, "character": 37 } },
"severity": 1,
"code": 9040403,
"source": "apilint",
"message": "Every step must have a unique 'stepId' within a workflow."
}
As you can see, this is a Language Server Protocol diagnostic. VS Code and every other LSP client already know how to render it. So the same output works in an editor, in a script, and in CI. Nothing needs translating.
Notice that nothing was thrown. A problem in the document is always a diagnostic. The validator throws only when it cannot read the document at all. Then you get a typed ValidateError, with the original error on cause (toolkit #201). So there are exactly two outcomes: a list, or the news that the document never arrived.
Why does it matter? Because of what people do with the list. They count the errors, and zero means “valid”. A validator has to earn that trust, and it can lose it in two ways:
I ran into both while getting this package ready.
The most dangerous bug in a validator is the one that produces no output. Nobody files an issue about a document that passed.
$refs in a JSON Schema resolve against a baseURI you pass in. I pointed a $ref at a missing file and got zero diagnostics, with baseURI and without. The referenceValidation check covers local #/... pointers only. The README now says so, and so does the API reference (toolkit #204).How did I find them? The same way as before: by writing the API reference for this site and running every sample in it. With the parser, the docs turned up five bugs. With the resolver, two of the ten. This time they caught the one that mattered most. Well, at least it was caught in time. The 1.1.0 fix landed before the first publish, so no published version has the bug.
The opposite failure is just as bad. A validator that reports errors on a valid document teaches people to ignore it.
Here is the one I hit. Every Reusable Object reported three errors. Reference a parameter, a success action, or a failure action from components, and the validator demanded fields a Reusable Object must not have. It also rejected reference as a field that is not allowed.
Why? The rules for a Parameter Object also ran on a Reusable Object that points at one. The OpenAPI rules guard against exactly this case. The Arazzo rules were written without the guard. So a document using Reusable Objects in all six places it can reported 18 errors. Now it reports none (toolkit #17).
There is a third way to lose trust, and it has nothing to do with diagnostics. An Arazzo document decides what its source descriptions point at, and the validator fetches them.
The default allow list for local files was ['*']. Looks harmless, right? In practice it let a document name any file on disk, /etc/passwd included, and the validator would read it. And because a glob like '*' never matches a dotfile, a perfectly ordinary ./.petstore.json was skipped. So the default was too open and too closed at the same time. Now it is the parser’s: local .json, .yaml, and .yml files, dotfiles included, and nothing else (toolkit #201).
Validating a document you did not write? The API reference has a section on untrusted documents. It shows how to turn resolution off, or how to keep it inside one directory.
Alpha means the API can still move before 1.0. Concretely:
validateURI takes a path or a URL. validate takes a document already in memory, as a TextDocument, which is what an editor holds.The feedback I want most:
Discussions is the place, and the monorepo is where the issues go.
Two things.
The first is more rules. My goal is to uncover as much as possible without running a workflow against a real API. Today the rules check a document’s own shape. Next they check what the document means:
$response.body#/id as a parameter value parses fine and is still wrong.operationId really exist in the OpenAPI document it names? Does a workflowId exist in the Arazzo document it names?That list lives in toolkit #197. If you have a rule idea, add it there.
The second is the CLI. The validator used to ship a command-line interface of its own. We took it out on purpose (toolkit #7). Two entry points for one job would only confuse people. And every package would carry its own argument parsing, output formats, and exit codes. So the command line gets one home, the UseArazzo CLI, and validation will be its first command. It is coming soon. Let me show you how it will look:
Coming soon
$ npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml adopt-a-pet.arazzo.yaml 16:9-18:38 error 9040403 Every step must have a unique 'stepId' within a workflow. 19:9-22:1 error 9040403 Every step must have a unique 'stepId' within a workflow. ✖ 2 problems (2 errors)$ npx @usearazzo/cli validate onboarding.arazzo.yaml onboarding.arazzo.yaml 16:9-17:32 warning 9050201 Step 'description' should be present and non-empty string. ⚠ 1 problem (1 warning)
The command and its formatting are a preview. The diagnostics are not. Each one is what the validator reports for that document today, with lines counted from 1. Compare the two runs. The first is the document from above, with its two errors. The second has only a warning, which is advice, not a violation.
So there it is. Until the CLI arrives, the library is there to be used. Start with the Arazzo Validator API reference, point it at a workflow you have written, and tell me what it got wrong.
]]>$refs, JSON Schema references, and the Reusable Objects that point into components, in Arazzo documents and in the OpenAPI documents they name.
npm install @usearazzo/resolver
The place to start is the Arazzo Resolver API reference. It covers every function, option, and error, and every output on that page came from a real run.
The rest of this post is about why “resolving” turned out to be three different jobs, and about the ten fixes it took in the layer underneath, in dereferencing and bundling both.
Ask three tool builders to “resolve the references” and you get three different programs. So the resolver has three operations, and the first decision you make is which one you need.
Why is this a separate package, and not an option on the parser? Because following a reference means file system and network access, caching, and cycle rules of its own. A parser that did all of that on every call would be the wrong tool for an editor that just wants a tree. The Parsing Arazzo Documents guide draws that line: a parser reads, a resolver dereferences.
The thing that took longest to get right is one idea, and it sits under dereferencing and bundling alike.
I started out thinking a reference points at a place: a file, and a path inside it. For the Reference Objects of OpenAPI 2.0 and 3.0 that is true, and both operations are simple. Dereferencing reads the place. Bundling copies it into components and points the reference at the copy.
JSON Schema 2020-12 changes it, and both OpenAPI 3.1 and Arazzo use it. A schema can declare its own identity with $id. Every relative $ref inside it resolves against that identity, not against the file it happens to sit in. So a resolver needs an index of identities, and that index has to stay right while the document changes under it.
Dereferencing reads that index. Bundling rewrites the document the index describes, so it is where most of the trouble showed up. Bundling is not copying. It is relocating, and relocating a schema changes what every relative reference around it means. One sentence sums it up: a bundle is only a bundle if you can move it. If the output still needs the directory it was made in, or the network, it is not self-contained, whatever it looks like.
The resolver stands on SpecLynx ApiDOM, which I also maintain, and that is where almost all of the work went. Ten issues, closed in two patch releases over four days.
It started with a review comment. The pull request that prepared the package for publishing came with a bundle fixture, and a comment on its expected output pointed out that the output was wrong. The fixture had enshrined the bug. That became toolkit #158, and pulling on it unravelled the rest.
In bundling:
$id was embedded, and then nothing pointed at it. The file was fetched as ./inputs.json but called itself https://example.com/schemas/inputs.json. The bundler embedded it under its own name and left the $ref as written, so the reference dangled. Now the $ref is rebased onto the embedded $id (#530).$id got an absolute path from my machine as one. The bundler assigned the retrieval URI, which for a file is an absolute path. The bundle leaked a machine-specific path and only worked in the directory it was made in. It now gets an $id relative to the entry document (#531).$refs inside it were carried along with the wrong base (#537). A schema it named elsewhere in the same document was never brought along (#546).In the $id lookup that dereferencing and bundling share:
$id index was a snapshot. Lookups went through metadata recorded once, at parse time, and the list was cached. Any $id assigned or changed afterwards was invisible. Worse, a schema with no identifiers matched any URI. Lookups now walk the real elements (#536, #540).$id and a $ref to its own $defs. The $id was never indexed, so both operations fell back to fetching that $id over HTTP (#541).All of that shipped in one ApiDOM release, and the resolver was published the next day.
Then I wrote the reference page, ran every sample, and two more things broke. Both are in dereferencing.
continueOnError did not cover Reusable Objects. A linter wants to process everything that works and report the rest. One bad reference: $components.parameters.missing still threw (#550).Element functions and both resolve functions, the petstore entry held the Arazzo document again, not the OpenAPI document it names (#551).Both were fixed in the next release, a day later, and the published resolver carries it. Both reproductions now pass against the package from npm.
Two are still open, both in dereferencing, and neither blocks normal use. A schema $ref cannot be served from a pre-computed set when every resolver is switched off (#554), and the location of an error inside a referenced document repeats a fragment (#555).
The lesson from the parser was that the samples in the docs are the best test suite a package has. That held again: two of the ten came from writing the reference. The new lesson is about fixtures. A fixture whose files all sit in one directory tests nothing about location, and location is the whole problem. And a saved expected output proves only that the output has not changed, never that it was right. The bundled.json that started all this was the bundler’s own broken output, saved and then asserted against. The test was green the whole time.
Alpha means the API can still move before 1.0. Concretely:
Element variants for dereference and resolve that take a tree you already parsed. Only whole documents bundle.resolve, parse, dereference, bundle. The Runner is the only consumer so far, so they may still move as other tools start using the package.The feedback I want most is the same as before, from people building their own Arazzo tooling: what did you have to work around, and what did you need that is not there? Discussions is the place, and the monorepo is where the issues go.
The Validator and the Runner are both in development and both unpublished. They now stand on two published layers, not one: a parser that reads, and a resolver that follows.
Until then, the resolver is there to be used. Start with the Arazzo Resolver API reference, bundle something that lives in more than one directory, move the result somewhere else, and tell me what breaks.
]]>npm install @usearazzo/parser
If you want to see it do something before reading further, the first tutorial builds a sixty-line script that lists every document a workflow depends on. It runs against the published package as-is.
The rest of this post is about why this package went first, and what I learned getting it out the door.
A few weeks ago I wrote that API workflows are still improvised and that UseArazzo is building the tooling to change that. The tools people actually want are the Validator and the Runner. Nobody wakes up wanting a parser.
But both of those tools need the same three things from the document before they can do their job. They need to know what every node is: that a string in a value field is a runtime expression and not just text, that steps is a list of Step Objects and not a bag of maps. They need to know where every node is, line and column, because a diagnostic without a position is a riddle and a run failure without one is a support ticket. And they need every document the workflow reaches, since a step can call an operation in one OpenAPI description and a workflow in another Arazzo document, each with source descriptions of its own.
The Runner already had its own expression parsing, and the Validator needs the same trees. Shipping either of them first would have meant shipping the same parser twice, privately, and fixing every bug in two places. So the parser came out alone, with its API documented. The Runner was moved onto it before the alpha was cut, and the Validator already depends on it.
There is a second reason. The Arazzo Ecosystem page lists more than twenty tools, and most of them started the same way: someone loaded a YAML file and got to work. I would rather the next editor plugin, linter, or agent integration not have to start from a YAML loader. A parser that is a dependency, not a product, is a better contribution to that ecosystem than a product would be.
The thing that took longest to get right is not any one feature. It is a shift in what I thought I was parsing.
I started out thinking of an Arazzo document as a file. It is not. It is several languages in one file: YAML or JSON on the outside, runtime expressions inside the strings, a condition grammar inside the criteria, JSON Pointer inside the expressions, JSON Schema for the inputs. And it is one file in a network: its source descriptions point at OpenAPI documents and at other Arazzo documents, and those point onwards. What a workflow means is spread across that network, so a parser that stops at the file has not finished.
The Parsing Arazzo Documents guide is the long version of that argument. What matters for this post is that once I took the network seriously, the bugs showed up on their own.
Every bug fixed in the fortnight before the release was found by writing documentation, not by writing code. I sat down to write the guide, ran every sample in it against the package, and four things broke.
memory:// URI, and the resolver serving it answered for any memory:// URI, so a relative source description that could not be found came back as the parent document itself. Fixed in #136.resolve.baseURI now supplies one, in #138.ParseError was not exported. You could catch it, but not by type. #141.Then I wrote the tutorial, ran its script, and found a fifth: pass a relative file path and the parser read the file fine, but resolved the source descriptions against the relative string as if it were a URL path. Reported as #147 and fixed in #148 the same day: a relative path now resolves against the working directory, in the parser, the resolver, and the Runner’s document registry alike.
I am not embarrassed by the list. Four of the five are about the network, and they are exactly the bugs you would expect from a parser written by someone who thought of a document as a file. The lesson I am taking is procedural: the samples in the docs are the best test suite the package has, because they are the tests a user would write.
Alpha means the API can still move before 1.0. Concretely:
parseArazzo, parseOpenAPI, parseRuntimeExpression, and parseCriterionCondition, and their result shapes are what I intend to keep. The API reference documents every option and every error they produce, and was checked against the type declarations and the source, not the README.parse.parserOpts may change as the Validator starts consuming the package and wants things the Runner did not.The feedback I want most is from people building their own Arazzo tooling: what did you have to work around, and what did you need that is not there? Discussions is the place, and the monorepo is where the issues go.
The Validator and the Runner are both in development and both unpublished. Each will get the same treatment: docs written against the code, samples run before release, a tutorial the day it lands, and a post like this one saying what it took.
Until then, the parser is there to be used. Start with the tutorial, read the guide if you want to know what a parser has to get right, and tell me what breaks.
]]>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, 1.0.1, and 1.1.0 workflows against OpenAPI 2.0, 3.0.x, and 3.1.x source descriptions. AsyncAPI isn’t supported yet. 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.
]]>