Validator and linter for Arazzo documents: semantic validation, semantic linting, and opt-in JSON Schema validation.

This package checks an Arazzo document and reports every problem it finds as an LSP Diagnostic, ready for an editor, a CI step, or a CLI:

• Semantic validation. Required fields, field types, and allowed values, for each Arazzo object.
• Semantic linting. Cross-object rules: step and workflow IDs resolve, runtime expressions parse, regex criterion conditions compile, $sourceDescriptions. references point at a source of the right type.
• Reference validation. Local $ref pointers inside JSON Schema objects (workflow.inputs, components.inputs) resolve to an existing target.
• JSON Schema validation, opt-in. Structural checks from the Arazzo JSON Schema, such as oneOf discrimination for Reusable Objects. Off by default because it reports a second diagnostic for many problems the linting rules already catch.

The types these work with are re-exported too: TextDocument, Diagnostic, DiagnosticSeverity, and LanguageServiceContext, plus the ARAZZO_LANGUAGE_ID and DEFAULT_DOCUMENT_VERSION constants createTextDocument fills in.

Problems in the document come back as diagnostics, never as thrown errors. validateURI throws ValidateError only when it cannot fetch the document (a missing file, an HTTP error, a disallowed location), with the underlying error on cause.

A relative path is read from the current working directory, just like with any Node.js file API.

npm install @usearazzo/validator

Ships ESM and CommonJS builds with TypeScript declarations. Requires Node.js 20.10 or newer.

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;

A URL works the same way, and relative source descriptions resolve against it:

const diagnostics = await validateURI('https://example.com/adopt-a-pet.arazzo.yaml');

When the content is already in memory, wrap it in a TextDocument and call validate. Relative sourceDescriptions[].url entries resolve against the TextDocument's URI, so give it the document's real, absolute location:

import { validate, createTextDocument } from '@usearazzo/validator';

const textDocument = createTextDocument('file:///home/me/specs/adopt-a-pet.arazzo.yaml', yamlText);
const diagnostics = await validate(textDocument);

Both functions take a SpecLynx ApiDOM Language Service context as their second argument, deep-merged over defaultLanguageServiceContext:

const diagnostics = await validateURI('./adopt-a-pet.arazzo.yaml', {
  validationContext: {
    jsonSchemaValidation: true, // default: false
    semanticValidation: true, // default: true
    referenceValidation: true, // default: true
    semanticLinting: true, // default: true
    betterAjvErrors: true, // default: true
  },
  parseContext: {
    fileAllowList: [/\.json$/i, /\.ya?ml$/i], // local files source descriptions may read (default)
    arazzo: {
      sourceDescriptionsResolution: true, // fetch and parse source descriptions (default: true)
    },
  },
});

validateURI takes a third argument, the ApiDOM Reference resolve options used to fetch the entry document. They default to @usearazzo/parser's file and HTTP resolvers, exported as defaultArazzoResolveOptions:

const diagnostics = await validateURI('https://example.com/adopt-a-pet.arazzo.yaml', {}, {
  resolverOpts: { timeout: 10000 },
});

By default the validator reads only local .json, .yaml, and .yml files (dotfiles included) for the entry document and for source descriptions, but it does fetch every source description, local or remote. To validate a document you don't trust without touching the file system or the network beyond the document itself:

const diagnostics = await validateURI('./untrusted.arazzo.yaml', {
  parseContext: {
    fileAllowList: [],
    arazzo: { sourceDescriptionsResolution: false },
  },
});

The examples above are the happy path. Everything else is on usearazzo.com:

• UseArazzo Validator introduces the validator: what it checks, how it reports problems, and a preview of validating from the command line. Start here when you are deciding whether it fits.
• Validator API Reference covers every exported function: its options, the shape of a diagnostic and its codes, the errors it can throw, and every rule the validator runs, with its code and severity. Start here when you know what you want to call, or when you want to know what a diagnostic means.

• Arazzo 1.0.0
• Arazzo 1.0.1
• Arazzo 1.1.0

@usearazzo/validator is the checking layer of the arazzo-toolkit monorepo, beside @usearazzo/parser, @usearazzo/resolver, and @usearazzo/runner. Questions and ideas go to GitHub Discussions.