Last updated

Linting Arazzo workflows

Before you send your Warp API workflow into the time stream with Respect, you need to make sure it's rock-solid. A typo in an operationId or a broken reference could leave you stranded in 1889—or worse, vaporized. That's where linting comes in. Using Redocly CLI's lint command, you can validate your Arazzo file's syntax and references, catching errors early. Let's lint our Tesla blueprint retrieval workflow, fix common Warp-related issues, and see why this step is a time traveler's best friend.

Why lint Arazzo?

Linting checks your Arazzo file for mistakes—think of it as a pre-flight checklist for your Warp mission. It ensures:

  • Syntax is clean: No missing colons or misnested YAML.
  • References work: Every operationId (e.g., warpApi.timeTravel) matches the Warp OpenAPI spec.
  • Consistency: Inputs, outputs, and dependencies align properly.

Redocly CLI's lint command, unlike Respect's execution, doesn't hit the API—it's a static check. Catch errors here, and you'll save time (and timelines) when running with Respect later.

Setting Up Redocly CLI

Grab your Arazzo file—we'll use warp.arazzo.yaml from our Tesla mission. Ensure you're using a recent-version of Redocly CLI (post-Arazzo support). We recommend to use npx to get the latest version:

npx @redocly/cli@latest lint warp.arazzo.yaml

Linting the Tesla Blueprint Workflow

Here's the workflow we've been working with:

arazzo: "1.0.1"
info:
  title: "Tesla Blueprint Retrieval Guide"
  version: "1.0.0"
sourceDescriptions:
  - name: "warpApi"
    url: "https://api.warp.example.com/v1/openapi.yaml"
workflows:
  - workflowId: "retrieveTeslaBlueprint"
    summary: "Travel to 1889 to retrieve Tesla's lost blueprint and return safely"
    parameters:
      - name: "Authorization"
        in: "header"
        value: "Bearer $inputs.token"
    steps:
      - stepId: "setHomeAnchor"
        operationId: "warpApi.setAnchor"
        description: "Set an anchor in 2025."
        parameters:
          body:
            timestamp: "2025-02-19T12:00:00Z"
            description: "Mission start point - 2025 base"
        outputs:
          anchorId: "$response.body.id"
      - stepId: "create1889Timeline"
        operationId: "warpApi.createTimeline"
        description: "Create a timeline to 1889."
        parameters:
          body:
            name: "Tesla Mission 1889"
            destination_time: "1889-03-10T23:50:00Z"
        outputs:
          timelineId: "$response.body.id"
      - stepId: "jumpTo1889"
        operationId: "warpApi.timeTravel"
        description: "Travel to 1889."
        dependsOn: "create1889Timeline"
        parameters:
          body:
            destination: "$steps.create1889Timeline.outputs.timelineId"
      - stepId: "registerBlueprint"
        operationId: "warpApi.registerItem"
        description: "Register Tesla's blueprint."
        parameters:
          body:
            description: "Tesla's lost blueprint"
        outputs:
          itemId: "$response.body.id"
      - stepId: "returnTo2025"
        operationId: "warpApi.timeTravel"
        description: "Return to 2025 with the blueprint."
        dependsOn: "setHomeAnchor"
        parameters:
          body:
            destination: "$steps.setHomeAnchor.outputs.anchorId"
            items_transported:
              - "$steps.registerBlueprint.outputs.itemId"

Save it as warp.arazzo.yaml and lint it:

npx @redocly/cli lint warp.arazzo.yaml

Sample success output

If all's well, you'll see:

No issues found in warp.arazzo.yaml

Your workflow's ready to run with Respect—time travel approved!

Catching common issues

Let's break it on purpose and lint again. Say we typo operatioId:

- stepId: "jumpTo1889"
  operatioId: "warpApi.timeTravel"  # Oops, missed the "n"

Run lint and see the error.

Custom Rules: Use a redocly.yaml config to enforce specific checks:

lint:
  rules:
    arazzo-operation-id-exists: error
    arazzo-source-description-reachable: error

Then lint:

npx @redocly/cli lint warp.arazzo.yaml

If Warp's openapi.yaml is unreachable (e.g., typo in url), you might see: warn: Source description 'warpApi' at 'https://api.warp.example.com/v1/openapi.yaml' is not reachable

Tips for linting workflows

  • Check references early: Lint before Respect to avoid runtime 404s from bad operationIds.
  • Match the OpenAPI description: Ensure API operations (e.g., setAnchor) exist in the OpenAPI file.
  • Fix dependencies: Double-check dependsOn and $steps references.
  • Iterate fast: Lint after every edit; it's quicker than running Respect.
  • Mock first: If sourceDescriptions URLs are live, test with mocks to avoid network flakiness.

Why it matters

Linting with Redocly CLI is your Warp workflow's safety net. For the Tesla blueprint mission, it ensures timeTravel points to the right endpoint and dependsOn doesn't derail the sequence—before you risk a live jump. It's a fast, free check that keeps your Arazzo files tight, setting you up for a flawless Respect run.

Next, let's run this linted workflow with Respect and watch Tesla's blueprint come home!

 
Next page