OpenAPI Arazzo & Overlay: Workflows and Spec Management

The OpenAPI ecosystem is no longer a single specification. The OpenAPI Initiative has published two companion standards — the OpenAPI Overlay Specification and the OpenAPI Arazzo Specification — that extend what you can describe about your APIs beyond individual endpoints. Overlay handles repeatable, non-destructive modifications to OpenAPI descriptions. Arazzo defines sequences of API calls as structured workflows. Together with the core OpenAPI Specification, they form a three-specification ecosystem for describing API behavior, managing API descriptions across environments, and orchestrating multi-step interactions.

If you manage APIs through a gateway, generate developer documentation from specs, or build tooling for AI agents that consume APIs, these new standards are worth understanding now — even as tooling continues to mature.

What Are the New OpenAPI Specifications?

The OpenAPI Initiative highlighted both Overlay and Arazzo at DeveloperWeek in February 2026. While the core OpenAPI Specification describes individual API operations — paths, parameters, request bodies, responses — it was never designed to capture how those operations relate to each other or how the spec itself should be modified across different contexts.

Overlay and Arazzo fill those gaps:

Overlay Specification — Defines a document format for changes that augment an existing OpenAPI description without modifying the source. Think of it as a patch layer for your API spec.
Arazzo Specification — Defines how to describe sequences of API calls, the dependencies between them, and the conditions for success or failure. Think of it as a workflow definition that sits on top of one or more OpenAPI descriptions.

Both are standalone specifications maintained under the OpenAPI Initiative as Linux Foundation Collaborative Projects.

OpenAPI Overlay: Repeatable Modifications to API Descriptions

The Overlay Specification (currently at v1.0.0, with v1.1.0 adding a copy action) solves a problem every API team hits eventually: you need different versions of your OpenAPI description for different audiences or environments, but you don’t want to maintain multiple copies of the spec.

An Overlay is a JSON or YAML document containing an ordered list of actions applied to a target OpenAPI description. Each action uses a JSONPath expression to select nodes in the target document, then either updates (merges new data) or removes them.

Overlay Structure

An Overlay document has four top-level fields:

overlay — The specification version (e.g., "1.0.0")
info — Metadata including a title and version for the overlay itself
extends — An optional URI reference pointing to the target OpenAPI document
actions — An ordered array of Action Objects, each with a target (JSONPath expression) and either an update (object to merge) or remove (boolean flag)

Here’s a practical example — an overlay that adds a security scheme and server URLs for a staging environment:

yaml

overlay: "1.0.0"
info:
  title: Staging Environment Overlay
  version: 1.0.0
extends: ./api.openapi.yaml
actions:
  - target: "$.servers"
    update:
      - url: https://staging-api.example.com
        description: Staging environment
  - target: "$.components.securitySchemes"
    update:
      api_key:
        type: apiKey
        in: header
        name: X-API-Key
  - target: "$.paths[*][*]"
    update:
      security:
        - api_key: []

This overlay is applied in sequence: first it sets the server URL to staging, then adds an API key security scheme, and finally applies that scheme to every operation. The original OpenAPI document stays unchanged.

Use Cases for Gateway Teams

Overlay is especially valuable for teams managing APIs through a gateway:

Environment-specific configuration — Maintain a single OpenAPI source of truth and use overlays to set different server URLs, security schemes, or metadata for dev, staging, and production.
Corporate security policies — Apply standardized security requirements across all APIs without editing each spec individually.
Documentation customization — Add or remove descriptions, examples, or internal-only extensions before publishing to external consumers.
Gateway metadata injection — Add vendor extensions (like gateway routing or policy configuration) as an overlay rather than embedding them in the source spec.
Localization — Translate descriptions and summaries into different languages without maintaining parallel spec files.

Because overlays are deterministic and ordered, they integrate naturally into CI/CD pipelines. You can version your overlays alongside your API spec in git and apply them automatically during deployment.

OpenAPI Arazzo: Describing API Call Sequences

The Arazzo Specification (v1.0.0, with a v1.0.1 patch release in January 2025) addresses something the core OpenAPI Specification was never built to express: how API calls relate to each other in a workflow.

Most APIs require multi-step interactions. Creating a payment requires first creating a customer, then creating a payment method, then initiating the charge. Onboarding a user might involve registration, email verification, profile creation, and subscription setup. Until Arazzo, there was no standard way to describe these sequences — developers relied on prose documentation, tutorials, or trial and error.

Arazzo Structure

An Arazzo document connects to one or more OpenAPI descriptions and defines workflows as ordered sequences of steps:

arazzo — The specification version
info — Metadata about the workflow document
sourceDescriptions — References to the OpenAPI specs (or other Arazzo documents) whose operations the workflows call
workflows — An array of workflow definitions, each containing steps, inputs, outputs, and dependencies
components — Reusable parameters, inputs, and success actions

Each step within a workflow references a specific API operation (by operationId or JSON Pointer) and defines:

Parameters — Values injected into path, query, header, or cookie parameters
Request body — The payload to send
Success criteria — Assertions that must pass (using JSONPath, regex, XPath, or simple expressions) for the step to succeed
Success and failure actions — What happens next: continue to the next step, jump to a different step, retry, or end the workflow
Outputs — Named values extracted from the response for use in subsequent steps

Here’s a simplified example — a workflow for creating and verifying a user account:

yaml

arazzo: "1.0.1"
info:
  title: User Onboarding Workflow
  version: 1.0.0
sourceDescriptions:
  - name: userApi
    url: ./user-api.openapi.yaml
    type: openapi
workflows:
  - workflowId: user-onboarding
    summary: Create and verify a new user account
    inputs:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
    steps:
      - stepId: create-user
        operationId: userApi.createUser
        requestBody:
          payload:
            email: $inputs.email
            name: $inputs.name
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          userId: $response.body#/id
          verificationToken: $response.body#/verificationToken
      - stepId: verify-email
        operationId: userApi.verifyEmail
        parameters:
          - name: token
            in: query
            value: $steps.create-user.outputs.verificationToken
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          verified: $response.body#/verified

The workflow explicitly defines the data flow between steps — the userId and verificationToken from the first step feed directly into the second. There’s no ambiguity about the order, the expected status codes, or which values carry forward.

Arazzo and AI Agent Workflows

Arazzo is particularly relevant as AI agents become first-class API consumers. When an LLM-powered agent needs to accomplish a task that spans multiple API calls, it typically reasons through the sequence in its context window — figuring out which endpoint to call next, what parameters to pass, and how to handle errors. This approach is fragile and expensive.

Arazzo shifts that orchestration logic out of the LLM’s reasoning loop and into a structured, deterministic specification. Instead of exposing every individual API operation as a tool and hoping the agent figures out the right sequence, you expose workflow-level capabilities that define the complete sequence up-front.

This pattern works well with the Model Context Protocol (MCP), where Arazzo workflows could be surfaced as MCP tools — each tool representing a complete business capability rather than a raw API call. The result is less context sprawl, fewer hallucinated API calls, and more reliable agent behavior. While production tooling for this integration is still emerging, the architectural fit between Arazzo’s deterministic workflows and MCP’s tool abstraction is compelling.

OpenAPI 4.0 “Moonwalk”: What’s Coming

OpenAPI 4.0, codenamed “Moonwalk,” is an active exploratory effort with no firm release date. The Moonwalk Special Interest Group (SIG) is using Architectural Decision Records (ADRs) and weekly open calls to explore what a major version should include, but no formal specification document has been drafted yet.

The 2026 focus has shifted significantly toward making OpenAPI work better with LLMs and AI agents. The SIG is investigating what additional metadata or structural information OpenAPI documents need to be more “agent-ready” — including capability discovery, intent signaling, and support for non-REST API patterns like RPC.

Other areas of exploration include:

Multi-path segment support and flexible URL patterns
Simplified specification structure for both human and machine readability
Signatures and improved security scheme definitions

For production use today, OpenAPI 3.1.x remains the most widely adopted version, though OpenAPI 3.2.0 was released in September 2025 with improvements including hierarchical tags, OAuth 2.0 Device Authorization Flow support, and the ability to deprecate security schemes. If you’re building tooling or making architectural decisions, build for 3.1 or 3.2 now and track Moonwalk for future planning.

How OpenAPI-Native Gateways Benefit from These Standards

If your API gateway treats OpenAPI as an optional documentation artifact — something you import, convert, and then forget about — Overlay and Arazzo don’t change much for you. But if your gateway is OpenAPI-native, meaning the OpenAPI spec is the gateway configuration, these new specifications extend the foundation you’re already building on.

Overlay + Gateway Configuration Management

An OpenAPI-native gateway like Zuplo uses your OpenAPI document (routes.oas.json) as the actual routing and validation configuration. The spec defines paths, methods, request schemas, and — through vendor extensions like x-zuplo-route — handlers and policies. This means the gateway and your documentation are always in sync because they derive from the same file.

Overlay fits this model naturally. Instead of maintaining separate OpenAPI files for each environment or audience, you maintain one canonical spec and apply overlays at deployment time:

A staging overlay swaps server URLs and relaxes rate limits
A partner overlay removes internal-only operations and adds partner-specific authentication
A production overlay injects gateway-specific extensions and tightens security policies

Because Zuplo supports GitOps workflows — where your gateway configuration lives in a git repository and deploys through CI/CD — overlays become just another file in the repo. Your deployment pipeline applies the right overlay for the target environment, and the gateway picks up the transformed spec automatically.

Arazzo + Developer Portal Documentation

Zuplo’s developer portal generates API documentation directly from your OpenAPI specification. Today, that documentation covers individual operations — endpoints, parameters, schemas, and examples. Arazzo opens the door to documenting workflows: the multi-step sequences that developers actually need to follow to accomplish real tasks.

Imagine your developer portal showing not just a list of endpoints, but guided walkthroughs: “To process a payment, call these three endpoints in this order, passing these values between them.” That’s what Arazzo descriptions enable.

Schema Validation Across Workflows

Zuplo already validates incoming requests against your OpenAPI schemas at the edge, rejecting malformed requests before they reach your backend. As Arazzo adoption grows, there’s a natural extension: validating not just individual requests but entire workflow sequences — ensuring that the output of step one matches the expected input of step two, and that the overall sequence conforms to the defined workflow.

Gateway Integration Examples

Using Overlay for Environment-Specific Gateway Config

Here’s how a team might use overlays with an OpenAPI-native gateway. Start with your base spec:

yaml

# api.openapi.yaml (base spec)
openapi: "3.1.0"
info:
  title: Payment API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /payments:
    post:
      operationId: createPayment
      summary: Create a new payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentRequest"
      responses:
        "201":
          description: Payment created

Then define an overlay for your staging environment:

yaml

# overlays/staging.overlay.yaml
overlay: "1.0.0"
info:
  title: Staging Environment
  version: 1.0.0
extends: ../api.openapi.yaml
actions:
  - target: "$.servers"
    update:
      - url: https://staging-api.example.com
        description: Staging environment
  - target: "$.paths['/payments'].post"
    update:
      x-zuplo-route:
        handler:
          export: urlForwardHandler
          module: "$import(@zuplo/runtime)"
          options:
            baseUrl: https://staging-payments.internal.example.com
        policies:
          inbound:
            - api-key-inbound

In your CI/CD pipeline, apply the overlay before deployment. The exact command depends on your overlay tooling — for example, using a tool like Speakeasy or a similar CLI:

bash

# Apply the staging overlay (tool-specific syntax varies)
openapi-overlay apply --overlay overlays/staging.overlay.yaml --schema api.openapi.yaml > config/routes.oas.json

# Deploy to Zuplo
zuplo deploy --environment staging

The base spec stays clean and readable. Environment-specific concerns live in their own versioned files.

Using Arazzo to Document Agent Workflows

Here’s how an Arazzo workflow could describe an e-commerce checkout sequence that an AI agent might execute:

yaml

arazzo: "1.0.1"
info:
  title: E-Commerce Checkout
  version: 1.0.0
sourceDescriptions:
  - name: cartApi
    url: ./cart-api.openapi.yaml
    type: openapi
  - name: paymentApi
    url: ./payment-api.openapi.yaml
    type: openapi
workflows:
  - workflowId: checkout
    summary: Complete a purchase from cart to payment confirmation
    inputs:
      type: object
      properties:
        cartId:
          type: string
        paymentMethodId:
          type: string
    steps:
      - stepId: get-cart
        operationId: cartApi.getCart
        parameters:
          - name: cartId
            in: path
            value: $inputs.cartId
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          totalAmount: $response.body#/total
          items: $response.body#/items

      - stepId: create-order
        operationId: cartApi.createOrder
        requestBody:
          payload:
            cartId: $inputs.cartId
            items: $steps.get-cart.outputs.items
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          orderId: $response.body#/orderId

      - stepId: process-payment
        operationId: paymentApi.chargePayment
        requestBody:
          payload:
            orderId: $steps.create-order.outputs.orderId
            amount: $steps.get-cart.outputs.totalAmount
            paymentMethodId: $inputs.paymentMethodId
        successCriteria:
          - condition: $statusCode == 200
          - condition: $response.body#/status == "confirmed"
        outputs:
          confirmationId: $response.body#/confirmationId

This Arazzo document tells both humans and machines exactly how the checkout works — which APIs are involved, what data flows between steps, and what constitutes success at each stage. An AI agent reading this workflow doesn’t need to guess the sequence or hallucinate parameter names.

What to Do Today

These specifications are still early in terms of tooling support, but the standards themselves are stable. Here’s how to get started:

Audit your OpenAPI workflow — If you maintain multiple versions of your spec for different environments or audiences, you’re already doing what Overlay formalizes. Evaluate whether a structured overlay approach would simplify your pipeline.
Document your multi-step flows — Identify the API workflows that developers struggle with most. Even if you don’t adopt Arazzo tooling immediately, thinking about your API in terms of workflows (not just endpoints) improves your documentation and developer experience.
Build on OpenAPI 3.1 or 3.2 — Both Overlay and Arazzo work with OpenAPI 3.1 descriptions (and 3.2, which is backward-compatible). If you’re still on OpenAPI 3.0 or 2.0, upgrading is the prerequisite for taking full advantage of the new specifications.
Adopt an OpenAPI-native gateway — If your gateway treats OpenAPI as an import artifact, you’ll get limited benefit from Overlay. An OpenAPI-native gateway that uses the spec as its configuration makes overlays a natural part of deployment.
Watch the tooling ecosystem — Most major API tool providers have Arazzo and Overlay on their roadmaps. Track the Overlay and Arazzo GitHub repositories for tooling announcements and spec updates.

The OpenAPI ecosystem is evolving from a single-specification standard into a family of complementary specifications. Overlay and Arazzo address real gaps that API teams have worked around for years — maintaining environment-specific specs and documenting multi-step workflows. Whether you adopt them now or later, they represent the direction the industry is heading.

Want to manage your APIs with a gateway that treats OpenAPI as the source of truth — not an afterthought? Get started with Zuplo and see how an OpenAPI-native gateway makes specs, routing, validation, and documentation work as one.