Arazzo Toolkit

JavaScript/TypeScript libraries and a command-line tool for parsing, resolving, validating, and running Arazzo Specification documents.

Website · Docs · Discussions · Issues

Packages

This monorepo contains the following packages:

Package	Description
@usearazzo/cli	Command-line interface for the toolkit: validate Arazzo documents from the terminal and CI
@usearazzo/validator	Validator and linter for Arazzo documents, reporting LSP diagnostics
@usearazzo/runner	Runs Arazzo workflows step by step against live APIs, with a trace of every step
@usearazzo/parser	Parser for Arazzo documents, producing the SpecLynx ApiDOM data model. API reference
@usearazzo/resolver	Dereferences, bundles, and resolves the references in Arazzo and OpenAPI documents. API reference

---

CLI

@usearazzo/cli puts the toolkit behind a single usearazzo binary for your terminal or CI/CD pipeline. Its one command today is validate, which wraps @usearazzo/validator and exits non-zero when the document has errors.

npx @usearazzo/cli validate ./adopt-a-pet.arazzo.yaml

Settings for the validator can live in a YAML or JSON configuration file (.usearazzo.yaml, .usearazzo.json, and a few variants) in the working directory. See the product page for what it does and the CLI reference for every option, output format, exit code, and the configuration file.

---

Validator

@usearazzo/validator checks an Arazzo document and reports every problem it finds as a Language Server Protocol diagnostic, with its location, severity, and rule code.

npm install @usearazzo/validator

import { validateURI, DiagnosticSeverity } from '@usearazzo/validator';

const diagnostics = await validateURI('./adopt-a-pet.arazzo.yaml');
const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);

To validate from the terminal or CI without writing code, use the CLI:

npx @usearazzo/cli validate ./adopt-a-pet.arazzo.yaml

See the product page for what it checks and the API reference for every option, diagnostic code, and rule.

---

Runner

@usearazzo/runner runs an Arazzo workflow. For each step it sends a real HTTP request to the API its OpenAPI source description points at, checks the step's success criteria against the response, and follows the control flow the document declares: goto, retry, end, sub-workflows, and dependsOn. A run hands back the workflow's outputs and a trace of every step.

npm install @usearazzo/runner

Here it runs a workflow that logs in, finds a pet, orders it, and checks the order, against a local Petstore (the public one rejects orders):

Text version

$ docker run --rm -d -p 8080:8080 swaggerapi/petstore3:1.0.28
e7d2c5a17eb5b5b8c316000c8987d5d4a6c2f93ba161c5bd6fb1cec26cfc9d9a
$ node
Welcome to Node.js v24.10.0.
Type ".help" for more information.
> .editor
// Entering editor mode (Ctrl+D to finish, Ctrl+C to cancel)
const { ArazzoRunner } = await import('@usearazzo/runner');

const runner = await ArazzoRunner.load(
  'https://usearazzo.com/assets/reference/runner/petstore-order.arazzo.yaml',
);
const result = await runner.execute('authenticateAndOrderPet', {
  inputs: { username: 'theUser', password: '12345', preferredPetStatus: 'available', orderQuantity: 1 },
  executeOptions: { server: 'http://localhost:8080/api/v3' },
});
result.steps.map((s) => `${s.successful ? '✓' : '✗'} ${s.stepId}`);

[
  '✓ loginUser',
  '✓ findAvailablePets',
  '✓ placeOrder',
  '✓ retrieveOrderedPetDetails',
  '✓ verifyOrderConfirmation'
]
> result.status
'completed'

ArazzoRunner.load and execute run a workflow in two calls, and its four building blocks stay public for composing your own. See the product page for what it handles and the API reference for every option, result field, and error.

---

Supported versions

Arazzo documents:

• Arazzo 1.0.0
• Arazzo 1.0.1
• Arazzo 1.1.0

OpenAPI documents, as source descriptions:

• OpenAPI 2.0
• OpenAPI 3.0.x
• OpenAPI 3.1.x

Contributing

Please read our Contributing Guide and Code of Conduct before submitting a pull request.

Origins

Arazzo Toolkit was founded on Jentic Arazzo Tools, Apache 2.0, from commit c696c9. The parser, resolver, and runner originate there and are developed further here. See NOTICE for full attribution.

License

This project is licensed under the Apache 2.0 License and comes with an explicit NOTICE file containing additional legal notices and information.