Arazzo: Defining Executable API Workflows

Purpose: Machine-Readable API Sequences Beyond Static Specs

Arazzo fills a gap in API descriptions like OpenAPI by defining workflows—specific sequences of calls with dependencies to achieve outcomes. It enables human- and machine-readable articulation of how APIs work together, improving developer experience through executable documentation. Unlike static OpenAPI paths, Arazzo weaves calls into stories: search, select, purchase a pet via sequenced endpoints.

Key insight: Workflows reference external API specs (e.g., OpenAPI YAML) via sourceDescriptions, avoiding duplication. Root document (arazzo.json or .yaml) uses JSON Schema types, supports YAML 1.2 for round-tripping, and follows major.minor.patch versioning where patches clarify without feature changes.

"The aim of the Arazzo Specification is to provide a mechanism that can define sequences of calls and their dependencies to be woven together and expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions)."

Data types mirror JSON Schema 2020-12 (string, number, integer, etc.) with OpenAPI-like formats: int32, int64, float, double, password. URLs support relative references per RFC3986.

Core Structure: Root Objects for Self-Contained Workflows

Every Arazzo Description MUST include:

• arazzo: REQUIRED version string (e.g., "1.0.1").
• info: Metadata with title, version, optional summary/description (CommonMark supported).
• sourceDescriptions: Array of sources (name, url, type: "openapi" or "arazzo"), at least one.
• workflows: Array of workflows, at least one.
• Optional components for reusables.

Example root (petstore purchase):

arazzo: 1.0.1
info:
  title: A pet purchasing workflow
  # ...
sourceDescriptions:
  - name: petStoreDescription
    url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
    type: openapi
workflows:
  - workflowId: loginUserAndRetrievePet
    # steps follow

Source names follow [A-Za-z0-9_-]+; URLs are URI-references. Workflows have unique workflowId (same regex), optional summary/description/inputs (JSON Schema), dependsOn (workflowIds or expressions like $sourceDescriptions.petStoreDescription.loginUser), steps (REQUIRED), workflow-wide parameters/successActions/failureActions/outputs (maps to expressions, keys ^[a-zA-Z0-9._-]+$).

"An Arazzo Description uses and conforms to the Arazzo Specification, and MUST contain a valid Arazzo Specification version field (arazzo), an info field, a sourceDescriptions field with at least one defined Source Description, and there MUST be at least one Workflow defined in the workflows fixed field."

Multi-document support: Entry doc holds root; others referenced via sources.

Steps: API Calls with Overrides and Flow Control

Steps are ordered lists in workflows, each a call to an operation (operationId or operationPath like {$sourceDescriptions.petstoreDescription.url}#/paths/~1pet~1findByStatus/get) or sub-workflow (workflowId). Fields mutually exclusive: pick one of operationId/path/workflowId. Use expressions for cross-source refs (e.g., $sourceDescriptions.<name>.operationId).

Pet login step example:

- stepId: loginStep  # unique per workflow, [A-Za-z0-9_-]+
  operationId: loginUser
  parameters:
    - name: username
      in: query
      value: $inputs.username  # runtime expression
  successCriteria:
    - condition: $statusCode == 200
  outputs:
    sessionToken: $response.body

Overrides: Step params/bodies/actions inherit from workflow but override (never remove). requestBody supported (avoid on GET/HEAD/DELETE). successCriteria: All Criterion conditions (expressions) MUST pass. Outputs map response parts (e.g., $response.header.X-Rate-Limit, $steps.prevStep.outputs.token).

Control: onSuccess/onFailure arrays of actions with optional criteria; first match executes. Default success: next step; failure: break. Workflow outputs aggregate step outputs (e.g., available: $steps.getPetStep.outputs.availablePets).

"All assertions MUST be satisfied for the step to be deemed successful."

Parameters: {name, in, value} (expression); requestBody schema/object. Reusables reference components.parameters etc.

Reusability, Actions, and Expressions

components: Schemas for parameters, successActions, failureActions. SuccessAction/FailureAction: action ("continue", "stop", "retry", etc.?—spec truncated but implies), optional criteria, times (retry count).

Runtime expressions: $inputs.*, $steps.*.outputs.*, $response.*, $statusCode, $sourceDescriptions.*. Enables dependency chaining (e.g., auth token from login to next call's Authorization: $steps.loginStep.outputs.sessionToken).

Extensions: Vendor prefixes for custom fields. Case-sensitive keys except noted.

This creates composable, executable API narratives: tooling can generate SDKs, tests, docs from workflows.

Key Takeaways

• Name entry files arazzo.json or .yaml and ensure root fields for validity.
• Reference OpenAPI sources via sourceDescriptions with unique names matching programming conventions.
• Use unique workflowId/stepIds with [A-Za-z0-9_-]+ regex for tooling.
• Chain dependencies with expressions like $steps.prev.outputs.token in params/outputs.
• Define successCriteria with $statusCode == 200 etc.; all must pass.
• Override workflow params/actions at step level without removal.
• Aggregate workflow outputs from steps for higher-level results.
• Prefer operationId over operationPath; use expressions for multi-source disambiguation.
• Leverage components for reusable params/actions across workflows.