DOCSEARCHbyAlgolia
Submit Docs

Arazzo Specification

repository·main·Indexed 19 days ago

https://github.com/oai/arazzo-specification

An open, programming language-agnostic standard for describing sequences of API calls (workflows) and their dependencies. Arazzo bridges the gap between individual API endpoints, such as those defined in OpenAPI or AsyncAPI, and functional business processes to enable interactive documentation, automated SDK generation, testing, compliance, and AI integration.

Tokens
32.1K
Snippets
56
Records
81
Agent score
63%

What's inside Arazzo Specification

  1. Explore Arazzo Tooling Ecosystem

    main

    The Arazzo ecosystem includes various tools for different stages of the workflow lifecycle. You can find a comprehensive list at openapi.tools.

    ### Editors, Design Tools, and Renderers
- **Arazzo Editor (Jentic)**: Form-based editing with real-time diagrams.
- **Arazzo Editor (Symplr)**: Visualize, execute, and publish workflows.
- **Arazzo UI**: Interactive documentation with diagram and documentation views.
- **API Flows Studio**: Web app to load and display Arazzo Workflow Documents.
- **ApiTapVia**: Visualizes Arazzo files as Markdown or mermaidjs.

### Generators
- **Arazzo Generator (Jentic)**: Analyzes OpenAPI specs to generate workflows based on patterns.
- **Arazzo Generator (JaredCE)**: Generates workflows from OpenAPI documents.
- **Specmatic**: Authoring, generation, mocking, and testing.

### Validation and Linting
- **Arazzo Validator**: Performs JSON Schema, semantic validation, and semantic linting.
- **Redocly CLI**: All-in-one utility for OpenAPI, AsyncAPI, and Arazzo.
- **Spectral**: Linter for API governance and style guides.
- **Speakeasy OpenAPI**: CLI tools for validation and bundling.

### Parsers and Resolvers
- **Arazzo Parser**: TypeScript/JavaScript parser for 1.0.0 and 1.0.1.
- **Arazzo Resolver**: TypeScript/JavaScript resolver/dereferencer.
- **Arazzo Runtime Expression**: Parser, validator, and extractor for runtime expressions.
- **Itarazzo**: Library to parse, validate, and execute specifications.

### Workflow Execution and Testing
- **arazzo-cli**: Standalone 1.0 executor with runtime engine, debugger, and MCP server for AI agents.
- **Arazzo Runner**: Execution engine for Arazzo workflows and OpenAPI calls.
- **Respect CLI**: Runs workflows and evaluates success criteria (schemas, status codes, etc.).
- **Specmatic**: Authoring, generation, mocking, and testing.

### Converters
- **arazzo2openapi**: Converts Arazzo workflows to OpenAPI with type inference.
- **pyarazzo**: CLI to transform Arazzo into Markdown, PlantUML, etc.

### Mocking
- **Specmatic**: Simplified mocking of Arazzo workflows.

  2. What is the Arazzo Specification?

    main

    The Arazzo Specification is an open, programming language-agnostic standard used to express sequences of API calls and their dependencies. It allows developers to articulate functional workflows (use cases) that involve one or more API descriptions, such as OpenAPI or AsyncAPI.

    By defining these workflows in a deterministic, machine-readable format, Arazzo enables:

    • Interactive Documentation: Living workflow documentation for developers.
    • Automated Generation: Creating developer portals, SDKs, or code based on functional use cases.
    • Testing & Compliance: Automating test cases and regulatory compliance checks.
    • AI Integration: Providing deterministic API invocation instructions for LLMs and AI agents.

  3. What is an Arazzo Description

    main

    An Arazzo Description is a self-contained document (or set of documents) used to define API workflows. These workflows describe specific sequences of API calls and their dependencies required to achieve particular goals within the context of an API definition (such as OpenAPI).

    To be valid, an Arazzo Description MUST include:

    • An arazzo field containing a valid Arazzo Specification version.
    • An info field (Info Object).
    • A sourceDescriptions field containing at least one defined Source Description Object.
    • A workflows field containing at least one Workflow Object.

  4. Why use the `$self` field for identity

    main

    The $self field provides a stable, canonical identity for an Arazzo Description that is independent of its retrieval location.

    Even if a document is retrieved from a local file, a CDN cache, or an embedded multipart response, all internal and external references to that document MUST use the value defined in $self. This ensures stability when documents are mirrored or moved and allows security-restricted environments to locate documents via their canonical identity without making unauthorized network requests.

  5. Define a workflow step in Arazzo

    main

    A single workflow step in an Arazzo document describes an action within a sequence. A step can be one of three types:

    1. An OpenAPI Operation: A call to an existing API operation defined in an OpenAPI specification.
    2. An AsyncAPI Operation: A call to an operation defined in an AsyncAPI specification.
    3. A Workflow Object: A nested workflow that allows for modular or recursive step definitions.

    When defining a step, you must include the required fixed fields specified by the Arazzo schema to ensure the step can be correctly parsed and executed by tools.

  6. Use the Components Object for Reusability

    main

    The components object holds reusable objects (inputs, parameters, success actions, and failure actions) that can be referenced throughout an Arazzo Description.

    Important Scoping Rules:

    • Components are scoped to the Arazzo document they are defined in. A step in document "A" referencing a workflow in document "B" will not have access to document "A"'s components.
    • Keys used to identify components must match the regular expression: ^[a-zA-Z0-9\.\-_]+$ (e.g., User, user-name, my.org.User).

    Fixed Fields

    Field NameTypeDescription
    inputsMap[string, JSON Schema]Reusable JSON Schema objects for workflow inputs.
    parametersMap[string, Parameter Object]Reusable Parameter Objects.
    successActionsMap[string, Success Action Object]Reusable Success Action Objects.
    failureActionsMap[string, Failure Action Object]Reusable Failure Action Objects.
    components:
  parameters:
    storeId:
      name: storeId
      in: header
      value: $inputs.x-store-id
  inputs:
    pagination:
      type: object
      properties:
        page:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
  failureActions:
    refreshToken:
      name: refreshExpiredToken
      type: retry
      retryAfter: 1
      retryLimit: 5
      workflowId: refreshTokenWorkflowId
      criteria:
          - condition: $statusCode == 401

  7. Arazzo Specification Versioning and Format

    main

    Versioning

    The Arazzo Specification uses a major.minor.patch scheme:

    • major.minor (e.g., 1.0) designates the feature set.
    • .patch versions are for error corrections or clarifications and should not be used by tooling to distinguish between versions (e.g., 1.0.0 and 1.0.1 are treated as the same feature set).

    File Format

    An Arazzo Description is a JSON object that can be represented in either JSON or YAML format.

    Important Constraints:

    • All field names are case sensitive unless explicitly noted otherwise.
    • When using YAML, it is recommended to use YAML version 1.2 with the following constraints to ensure round-tripping to JSON:
      • Tags must be limited to those allowed by JSON Schema rulesets.
      • Keys in YAML maps must be limited to a scalar string (YAML Failsafe schema).

  8. Define success criteria for AsyncAPI receive steps

    main

    When a step performs an AsyncAPI receive operation, its completion depends on receiving a message. Because AsyncAPI channels can have multiple message types, you SHOULD define successCriteria to evaluate the received payload (e.g., using $message.payload).

    When you can omit successCriteria: You MAY omit successCriteria only if:

    1. The channel defines a single message type that unambiguously represents success.
    2. The message payload contains no fields indicating error states (like status codes or error flags).

    If successCriteria is omitted, the step is considered successful if any message matching the correlationId (if specified) is received within the timeout period. If no matching message arrives within the timeout, the step fails and triggers onFailure actions.

  9. Understand Arazzo Runtime Expressions

    main

    Runtime expressions allow you to define values dynamically based on the HTTP message or the Arazzo document state (inputs, outputs, steps, workflows, etc.).

    Syntax Structure

    An expression starts with a $ followed by a source identifier. Common sources include:

    • $url, $method, $statusCode
    • $request.<source> (e.g., $request.header.token, $request.query.name, $request.body#/<pointer>)
    • $response.<source> (e.g., $response.body#/<pointer>)
    • $inputs.<name>
    • $outputs.<name>
    • $steps.<name>
    • $workflows.<name>
    • $components.<name>
    • $components.parameters.<parameter-name>

  10. Manage step dependencies and execution order

    main

    Arazzo steps can be coordinated using explicit and implicit dependencies to manage execution flow, especially for asynchronous operations.

    Synchronous Workflows

    For linear, synchronous workflows, the RECOMMENDED approach is to simply order steps sequentially in the steps array. In this model, dependsOn is typically unnecessary.

    Asynchronous Coordination

    Use the dependsOn field to establish join points for asynchronous work. A step should declare dependsOn on the step that triggers an async operation to ensure the operation completes before the dependent step executes, even if there is no direct output reference.

    Implicit Dependencies

    Tools MUST treat runtime expression output references (e.g., $steps.stepId.outputs.field) as implicit dependencies. The referenced step must complete before the referencing step executes.

    Validation Note

    Implementations SHOULD error if a step references an output from a step that appears later in the steps array (a forward reference) when using a sequential execution model without dependsOn.

    - stepId: confirmOrder
  description: receiving a message payload to confirm an order
  operationId: $sourceDescriptions.asyncOrderApi.confirmOrder
  correlationId: $inputs.correlationId
  action: receive
  dependsOn:
    - placeOrder
  timeout: 6000
  outputs:
      orderId: $message.payload.orderId

  11. Define Source Descriptions

    main

    A sourceDescription object maps a named key to a location URL of a source description (such as an OpenAPI or AsyncAPI file) that the Arazzo workflows will reference.

    Each entry in the sourceDescriptions list allows workflows to reference operations or paths defined in that source using the $sourceDescriptions.{name} syntax.

    sourceDescriptions:
- name: petStoreDescription
  url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
  type: openapi

  12. Extend the Arazzo Specification with x- properties

    main

    You can add custom data to an Arazzo document using extension properties. These must follow a specific naming pattern to avoid collisions with the core specification.

    Extension Rules

    • Prefix: All extension field names MUST begin with x- (e.g., x-internal-id).
    • Reserved Prefixes: The following prefixes are reserved for the OpenAPI Initiative and should not be used for custom extensions:
      • x-oai-
      • x-oas-
      • x-arazzo
    • Value Types: The value of an extension can be null, a primitive, an array, or an object.

    Note that while you can add extensions, not all Arazzo tooling is required to support them.