Arazzo Specification

Write, review, and modify Arazzo workflow specifications that describe deterministic, multi-step API workflows on top of OpenAPI.

Workflow

Authoring a New Arazzo Document

1. Identify the business outcome the workflow achieves.
2. Collect the OpenAPI spec(s) involved and note the operationIds needed.
3. Read references/01-overview-and-structure.md for document skeleton and naming.
4. Read references/02-core-constructs.md for source descriptions, steps, parameters, request bodies, and runtime expressions.
5. Draft the document using the skeleton below.
6. Define each step: choose operationId (preferred), operationPath, or workflowId.
7. Thread data between steps using runtime expressions and step outputs.
8. Add success criteria to every step — read references/03-criteria-flow-outputs.md.
9. Add failure/success actions for known failure modes (rate limits, auth expiry) — same reference.
10. Extract repeated elements into components — read references/04-reuse-and-composition.md.
11. For sub-workflow composition, read references/04-reuse-and-composition.md.
12. Validate with the checklist below and recommend linting tools from references/06-ai-agents-validation-practices.md.

Reviewing an Existing Arazzo Document

1. Validate structure against the skeleton below.
2. Check every item in the best practices checklist below.
3. Read references/07-pitfalls-tooling-resources.md and scan for common pitfalls.
4. Verify all operationId references exist in the source OpenAPI document(s).
5. Verify all runtime expressions reference steps that precede them in sequence.
6. Suggest linting integration (Spectral, Redocly CLI).

For AI Agent / MCP Integration

• Read references/06-ai-agents-validation-practices.md for patterns on exposing Arazzo workflows as MCP tools and reducing LLM token consumption.

Document Skeleton

arazzo: "1.0.1"
info:
  title: Workflow Title
  version: "1.0.0"
  description: What this workflow achieves.

sourceDescriptions:
  - name: myApi          # Descriptive name, used as operationId prefix
    url: ./openapi.yaml
    type: openapi

workflows:
  - workflowId: my-workflow
    summary: One-line purpose.
    inputs:
      type: object
      properties:
        param_name:
          type: string
    steps:
      - stepId: first-step
        description: What this step does and why.
        operationId: myApi.someOperation
        parameters:
          - name: paramName
            in: query
            value: $inputs.param_name
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          result_id: $response.body#/id

      - stepId: second-step
        operationId: myApi.anotherOperation
        parameters:
          - name: id
            in: path
            value: $steps.first-step.outputs.result_id
        successCriteria:
          - condition: $statusCode == 200
    outputs:
      workflow_result: $steps.first-step.outputs.result_id

components:
  parameters: {}
  inputs: {}
  successActions: {}
  failureActions: {}

Runtime Expression Quick Reference

Embedding in strings: Use curly braces — "Bearer {$steps.auth.outputs.token}". When the entire value is an expression, no braces needed: value: $inputs.pet_id.

JSON Pointer: #/0/id = first array element's id. #/data/customer/email = nested field. Escape / as ~1, ~ as ~0.

Operation Reference Rules

Use exactly one per step (mutually exclusive):

Key Syntax Rules

• `$ref` is for JSON Schema references (in inputs schemas only).
• `reference` is for Arazzo's Reusable Object (in parameter/action arrays). Supports value override.
• Success criteria in an array are AND-ed. For OR, combine in one expression: $statusCode == 200 || $statusCode == 201.
• `dependsOn` declares prerequisites but does not invoke them.
• Failure action types: end, goto, retry (with retryAfter and retryLimit).
• All field names are case-sensitive (except HTTP header names).

Best Practices Checklist

Structure

• [ ] File named arazzo.yaml or arazzo.json.
• [ ] arazzo version field set to "1.0.1".
• [ ] summary and description on info, workflows, and steps.

Naming

• [ ] workflowIds reflect business outcomes: apply-coupon, not workflow1.
• [ ] stepIds reflect actions: search-pets, not step1.
• [ ] sourceDescription names are descriptive: payments, not api2.
• [ ] All IDs match [A-Za-z0-9_\-]+.

Operations & Data Flow

• [ ] operationId preferred over operationPath.
• [ ] Every operationId exists in the source OpenAPI document.
• [ ] Exactly one of operationId / operationPath / workflowId per step.
• [ ] Workflow inputs typed with JSON Schema.
• [ ] Outputs are minimal — only values consumed downstream.
• [ ] Every runtime expression references a preceding step.

Robustness

• [ ] successCriteria defined on every step.
• [ ] onFailure actions for rate limits (429), auth expiry (401).
• [ ] Reasonable retryAfter and retryLimit values.
• [ ] Workflow-level failureActions as defaults; step-level overrides where needed.

Reusability

• [ ] Repeated parameters (auth, pagination) in components/parameters.
• [ ] Shared input schemas in components/inputs.
• [ ] Common actions in components/successActions and components/failureActions.
• [ ] Multi-step reusable sequences as sub-workflows.

Maintenance

• [ ] Arazzo versioned alongside OpenAPI specs — single documentation unit.
• [ ] Linting in CI (Spectral or Redocly CLI).

References

• references/01-overview-and-structure.md — What Arazzo is, ecosystem context, document structure, first document walkthrough.
• references/02-core-constructs.md — Source descriptions, workflows, steps, parameters, request bodies, runtime expressions.
• references/03-criteria-flow-outputs.md — Success criteria, control flow (success/failure actions), outputs and data threading.
• references/04-reuse-and-composition.md — Reusable components and workflow composition (local and cross-document).
• references/05-complete-example.md — End-to-end e-commerce checkout example demonstrating all features together.
• references/06-ai-agents-validation-practices.md — AI agent and MCP integration patterns, validation/linting tools, best practices checklist.
• references/07-pitfalls-tooling-resources.md — Common pitfalls, tooling ecosystem, and learning resources.