Lint Arazzo with Redocly CLI

Arazzo is an open standard from the OpenAPI Initiative for describing a sequence API calls, defining success criteria, and adding response content to subsequent API calls. While under development, this standard was also known as "OpenAPI Workflows". Redocly CLI offers support for checking that your Arazzo files are valid.

Lint an Arazzo file

Use your existing Arazzo files, or use the Arazzo examples in the Museum API project if you'd prefer to use sample data to try things out.

Pro-tip: linting is much more interesting if the file actually does contain problems. Be your own chaos monkey and introduce some errors before you proceed!

Lint using a command like the following:

redocly lint arazzo/museum-api.arazzo.yaml

If the file does not match the specification, the tool shows the details of each error that it finds, like in the following example:

validating arazzo/museum-api.arazzo.yaml...
[1] arazzo/museum-api.arazzo.yaml:18:5 at #/workflows/0

The field `workflowId` must be present on this level.

16 |
17 | workflows:
18 |   - workflooId: get-museum-hours
19 |     description: >-
 … |     < 20 more lines >
40 |   - workflowId: events-crud
41 |     description: >-
42 |       This workflow demonstrates how to list, create, update, and delete special events at the museum.

Error was generated by the spec rule.


[2] arazzo/museum-api.arazzo.yaml:18:5 at #/workflows/0/workflooId

Property `workflooId` is not expected here.

Did you mean: workflowId ?

16 |
17 | workflows:
18 |   - workflooId: get-museum-hours
19 |     description: >-
20 |       This workflow demonstrates how to get the museum opening hours and buy tickets.

Error was generated by the spec rule.


arazzo/museum-api.arazzo.yaml: validated in 14ms

❌ Validation failed with 2 errors.
run `redocly lint --generate-ignore-file` to add all problems to the ignore file.

Configure the linting rules

Choose from the ready-made rulesets (minimal, recommended or recommended-strict), or go one better and configure the rules that suit your use case. The rules available for linting Arazzo are:

• parameters-not-in-body: the in section inside parameters must not contain a body.
• sourceDescription-type: the type property of the sourceDescription object must be either openapi or arazzo.
• version-enum: the version property must be one of the supported values.
• workflowId-unique: the workflowId property must be unique across all workflows.
• stepId-unique: the stepId must be unique amongst all steps described in the workflow.
• sourceDescription-name-unique: the name property of the sourceDescription object must be unique across all source descriptions.
• workflow-dependsOn: the items in the workflow dependsOn property must exist and be unique.
• parameters-unique: the parameters list must not include duplicate parameters.
• step-onSuccess-unique: the onSuccess actions of the step object must be unique.
• step-onFailure-unique: the onFailure actions of the step object must be unique.
• requestBody-replacements-unique: the replacements of the requestBody object must be unique.
• no-criteria-xpath: the xpath type criteria is not supported by Spot.
• no-actions-type-end: the end type action is not supported by Spot.
• criteria-unique: the criteria list must not contain duplicated assertions.

Add the rules to redocly.yaml, but for Arazzo specifications, the rules go in their own configuration section called arazzoRules. The following example shows configuration for the minimal ruleset with some additional rules configuration:

extends:
 - minimal

arazzoRules:
  sourceDescription-name-unique: warn
  version-enum: error

The configuration shown here gives some good entry-level linting using the minimal standard, and adds checks that we're using a supported version of Arazzo, and warns if each source description doesn't have a unique name.

Choose output format

Since Redocly CLI is already a fully-featured lint tool, additional features such as a choice of formats are already included.

Get a report in Markdown format with the following command:

redocly lint --format=markdown arazzo/museum-api.arazzo.yaml

Choose your preferred output format from codeframe, stylish, json, checkstyle, codeclimate, github-actions, markdown, or summary. The lint command page has full details of the command's options.

Add Arazzo linting to GitHub Actions

To make sure that your Arazzo description remains valid, add linting to your CI (Continuous Integration) setup. You can use Redocly CLI with the github-actions output format to get annotations directly in your pull request if any validation problems are found. The following snippet shows an example of configuring a GitHub action for linting:

name: Validate museum Arazzo descriptions

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up node
        uses: actions/setup-node@v4
      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest
      - name: Run linting
        run: redocly lint arazzo/*yaml --format=github-actions

With this action in place, the intentional errors I added to the Arazzo description are shown as annotations on the pull request:

Participate in Redocly CLI

Redocly CLI is an open source project, so we invite you to check out the code on GitHub, and open issues to report problems or request features.