Can I install the Validator today?

Yes. Run npm install @usearazzo/validator. It is published as an alpha, so the API may still change before the stable release.

Can I run the Validator from the command line?

Yes. Run npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml. The UseArazzo CLI wraps the Validator, prints every problem with its location, and exits with 1 when there is an error, so it works in CI too. The CLI reference lists every option.

Is the Validator free?

Yes. @usearazzo/validator is free, open-source, and licensed under Apache 2.0.

Every Arazzo object against the specification: required fields, types, unique IDs, steps and workflows that must exist in the document, and runtime expression syntax. It also checks that local $ref pointers in JSON Schemas resolve. JSON Schema validation is available on top, opt-in. The API reference lists every rule.

Which Arazzo versions does it support?

Arazzo 1.0.0, 1.0.1, and 1.1.0.

Is it safe to run on documents I don't fully trust?

By default it reads only local .json, .yaml, and .yml files, and fetches the source descriptions a document names. For untrusted input, set fileAllowList: [] and sourceDescriptionsResolution: false, or confine reads to one directory.

UseArazzo Validator

Name: UseArazzo Validator
Author: UseArazzo

Published

Every violation against the Arazzo specification, with the location that caused it.

An Arazzo document can parse cleanly and still be wrong: two steps sharing an ID, a goto to a step that does not exist, a runtime expression that does not parse. @usearazzo/validator finds those problems before a run does, and reports each one with its line, its severity, and the rule it broke.

Read the API reference View source on GitHub

Supported versions:

✓ Arazzo 1.0.0, 1.0.1, 1.1.0

From the Terminal

The UseArazzo CLI puts the Validator behind a single command, for your terminal and your CI pipeline. The first document has two steps with the same ID, an error. The second has a step without a description, a warning.

usearazzo validate

$ 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-18:1  warning  9050201  Step 'description' should be present and non-empty string.

⚠ 1 problem (1 warning)

Need the diagnostics in your own code instead? They are one function call away. See Installation.

What It Checks

Every Arazzo object

Required fields, field types, and allowed values on every object, from the document root to criteria and actions. IDs must be unique, and the steps and workflows a document points at must exist in it. Runtime expressions must parse.

The version you wrote

Each document is checked against the Arazzo version in its own arazzo field. A dependsOn on a step passes in 1.1.0 and is reported in 1.0.1.

Diagnostics your tools understand

Every problem is a Language Server Protocol diagnostic: a range, a severity, a stable numeric code, and a message. Editors underline it, CI counts it, and your code can match on it.

Ready for untrusted documents

Only local JSON and YAML files are read. For a document you did not write, one option turns off everything beyond the document itself; another confines reads to a single directory.

The API reference lists every rule, with its code, severity, and message.

Installation

npm install @usearazzo/validator

Point it at a file or a URL, and count the errors:

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

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

Content already in memory, options, the shape of a diagnostic, and validating documents you do not trust are all in the API reference.

Rest of the Toolkit

Runner

Executes the workflows you validate here, interpreting the same Arazzo semantics.

Explore Runner

CLI

Puts this library behind a command, so validation runs from a terminal or a CI pipeline instead of your own code.

Explore CLI

Under the hood, the Validator uses @usearazzo/parser to fetch the documents it checks.

Frequently Asked Questions

: Yes. Run npm install @usearazzo/validator. It is published as an alpha, so the API may still change before the stable release.
: Yes. Run npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml. The UseArazzo CLI wraps the Validator, prints every problem with its location, and exits with 1 when there is an error, so it works in CI too. The CLI reference lists every option.
: Yes. @usearazzo/validator is free, open-source, and licensed under Apache 2.0.
: Every Arazzo object against the specification: required fields, types, unique IDs, steps and workflows that must exist in the document, and runtime expression syntax. It also checks that local $ref pointers in JSON Schemas resolve. JSON Schema validation is available on top, opt-in. The API reference lists every rule.
: Arazzo 1.0.0, 1.0.1, and 1.1.0.
: By default it reads only local .json, .yaml, and .yml files, and fetches the source descriptions a document names. For untrusted input, set fileAllowList: [] and sourceDescriptionsResolution: false, or confine reads to one directory.