Parser for the Arazzo Specification language: documents, runtime expressions, and criterion conditions.

An Arazzo document is three languages in one file. This package reads all of them:

• Documents. parseArazzo and parseOpenAPI turn an Arazzo or OpenAPI document, from a file, a URL, a string, or a plain object, into a typed SpecLynx ApiDOM tree with optional source positions.
• Runtime expressions. parseRuntimeExpression parses $inputs.x, $steps.y.outputs.z, $response.body#/a/b, and friends into an AST.
• Criterion conditions. parseCriterionCondition parses the simple criterion grammar, such as $statusCode == 200, into an AST.

The expression and condition parsers are pure syntax parsers: a string in, an AST plus diagnostics out, no evaluation and no document required. Evaluating them against runtime state is @usearazzo/runner's job.

Documents come back as ApiDOM, so source positions for editor tooling, formatting-preserving round trips, and one-call parsing of every source description an Arazzo document points at are all options away.

A relative file system path resolves against the current working directory, so ./samples/onboarding.arazzo.yaml and path.resolve('samples/onboarding.arazzo.yaml') are equivalent.

npm install @usearazzo/parser

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

import { parseArazzo } from '@usearazzo/parser';
import { toValue } from '@speclynx/apidom-core';

const parseResult = await parseArazzo('./adopt-a-pet.arazzo.yaml');

parseResult.errors.length; // 0
toValue(parseResult.api.info.title); // 'Pet adoption'
toValue(parseResult.api.workflows.get(0).workflowId); // 'adopt-a-pet'
parseResult.api.workflows.get(0).steps.length; // 2

The two grammar parsers are synchronous and need no document:

import { parseRuntimeExpression, parseCriterionCondition } from '@usearazzo/parser';

parseRuntimeExpression('$steps.findPet.outputs.petId').tree;
// { type: 'StepsExpression', stepId: 'findPet', field: 'outputs', outputName: 'petId' }

parseCriterionCondition('$statusCode == 200').result.success; // true
parseCriterionCondition('$statusCode ===').result.success; // false, and nothing thrown

The examples above are the happy path. Everything else is in the docs at usearazzo.com/docs:

• Parser API Reference covers every exported function: its options, from source maps to parsing source descriptions, the shape of what it returns, and the errors it can throw. Start here when you know what you want to call.
• Parsing Arazzo Documents explains what makes an Arazzo document hard to parse, what a parsed document should look like, and what a good parser gives you. Start here when you want to understand why the package is shaped the way it is.

Arazzo documents:

• Arazzo 1.0.0
• Arazzo 1.0.1
• Arazzo 1.1.0

OpenAPI documents, as source descriptions or on their own:

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

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