{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"arazzo-basics-structure-and-syntax","__idx":0},"children":["Arazzo basics: Structure and syntax"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ready to get your hands dirty with Arazzo? This guide will walk you through the nuts and bolts of the Arazzo Specification—its structure, its syntax, and how it all fits together. If you've worked with OpenAPI before, you'll feel right at home: Arazzo uses the same YAML or JSON format and builds on OpenAPI's foundation. Let's dive into what makes an Arazzo file tick and get you ready to write your first workflow."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-big-picture","__idx":1},"children":["The big picture"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An Arazzo file is a structured document that describes API workflows—sequences of calls with clear steps, dependencies, and outcomes. It's designed to be both human-readable (for you) and machine-readable (for tools). At its core, every Arazzo file has a few key pieces:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arazzo"]},": The version of the spec you're using (e.g., \"1.0.1\")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]},": Metadata like the title and version of your workflow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceDescriptions"]},": Links to OpenAPI or Arazzo files your workflows rely on."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflows"]},": The heart of Arazzo—where you define the sequences of API calls."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components"]},": Optional reusable bits you can reference elsewhere."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Think of it like a playbook: it tells you (or a tool) how to run the game, step by step. Let's break these down."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-anatomy-of-an-arazzo-file","__idx":2},"children":["The anatomy of an Arazzo file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's what each section does, with a simple example to tie it together."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arazzo"]}," (Required)"," ","This is the version marker. It tells everyone which Arazzo spec you're following. As of February 2025, the latest is 1.0.1 (a patch over the 1.0.0 release from 2024). It's always at the top:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"arazzo: \"1.0.1\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]}," (Required)"," ","This is your workflow's ID card—basic metadata to keep things organized. It needs a title and version, but you can add a description or summary for clarity:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"info:\n  title: \"Simple Workflow\"\n  version: \"1.0.0\"\n  description: \"A basic workflow to buy a ticket and confirm it's valid.\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceDescriptions"]}," (Required)"," ","This section points to the OpenAPI files your workflow uses. It's how Arazzo connects to existing API definitions. Each entry has a name (for reference) and a url (where the file lives) and a type (currently the only valid values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arazzo"]},"):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"sourceDescriptions:\n  - name: \"warpAPI\"\n    url: \"./warp/openapi.yaml\"\n    type: openapi\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":4},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflows"]}," (Required)"," ","Here's where the magic happens. The workflows section is an array of workflow objects, each defining a sequence of API calls. Every workflow needs:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflowId"]},": A unique identifier."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["summary"]},": A human-friendly overview."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]},": A detailed explanation of the workflow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["steps"]},": The actual sequence of operations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dependsOn"]},": Which workflow(s) it relies on (optional)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inputs"]},": Input parameters used by the workflow (optional)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inside steps, each step has:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stepId"]},": A unique name for the step."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]},": Links to an OpenAPI operation (from your sourceDescriptions)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parameters"]},": Inputs for the call (static or dynamic)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outputs"]},": What data it produces (optional)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Steps run in sequence by default, with each step using data from previous steps through runtime expressions."]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":5},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components"]}," (Optional)"," ","This is for reusable pieces—like parameters or steps—you might want to reference across workflows. It's like OpenAPI's components, but for Arazzo-specific stuff. We'll keep it simple and skip this for now."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"a-simple-example","__idx":3},"children":["A simple example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's put it together with a basic workflow for a time travel API: setting an anchor in time. Assume we've got an ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://warp-multi-sidebars.redocly.app/_spec/apis/index.yaml?download"},"children":["OpenAPI file"]}," with operation ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setAnchor"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"arazzo: 1.0.1\ninfo:\n  title: Warp API\n  version: 1.0.0\nsourceDescriptions:\n  - name: api-reference\n    type: openapi\n    url: openapi.yaml\nworkflows:\n  - workflowId: missionLostInvention\n    summary: Lost invention\n    description: |-\n      Travel back to the year 1889 and retrieve the blueprint for Nikola Tesla's lost invention before it's destroyed in a mysterious fire.\n    inputs:\n      type: object\n      properties:\n        token:\n          type: string\n          description: JWT Bearer token\n          format: password\n    parameters:\n      - name: Authorization\n        in: header\n        value: \"Bearer {$inputs.token}\"\n    steps:\n      - stepId: setAnchorToCurrentTime\n        operationId: api-reference.setAnchor\n        description: Set an anchor to the current time.\n        outputs:\n          anchor_id: $response.body#/id\n      - stepId: jumpTo1889\n        operationId: api-reference.timeTravel\n        description: \"Travel to 1889 using the created timeline.\"\n        requestBody:\n          payload:\n            destination: $steps.setAnchorToCurrentTime.outputs.anchor_id\n# to be continued -- see a full walkthrough of this example in the next article\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-happening-here","__idx":4},"children":["What's happening here?"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Top Level"]},": We declare Arazzo 1.0.1 and give our workflow a title and version."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Source"]},": We link to Warp's OpenAPI file."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workflow"]},": We define one workflow, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missionLostInvention"]},".",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 1"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setAnchorToCurrentTime"]}," calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setAnchor"]}," to set an anchor point in time."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 2"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jumpTo1889"]}," calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeTravel"]}," to travel to 1889 using the created timeline."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$"]}," syntax is a runtime expression—think of it as a placeholder that grabs data dynamically when the workflow runs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-ties-to-openapi","__idx":5},"children":["How it ties to OpenAPI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Arazzo doesn't reinvent the wheel—it leans on OpenAPI. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}," in each step (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setAnchor"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeTravel"]},") matches an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}," in the linked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api-reference"]}]}]},"frontmatter":{},"tagList":[],"title":"Arazzo basics: Structure and syntax","lastModified":"2025-09-10T18:10:19.000Z"}