When people say “OpenAPI”, they are usually referring to the OpenAPI Specification, the API description language that helps us publish and consume APIs. The OpenAPI Specification is at the center of how the API community describes the shape of an API, allowing it to be readily understood.

However, you may not realize that the OpenAPI Initiative (OAI) has expanded beyond the core OpenAPI Specification. The needs of the API community have grown alongside the continued increase in scale of the API economy, and the community needs are reflected in the evolution of OAI to a multi-specification project. Our view of the world at the end of 2024 includes some significant developments over the last 12 months, with an equally exciting 2025 ahead. The OAI now incorporates the following projects:

• OpenAPI Specification.
• Arazzo Specification.
• Overlay Specification.
• OAS Comply.
• Special Interest Groups (SIGs).

The tools, specifications, and groups that comprise the OAI project provide an increasingly large footprint of standards in the API economy. Their relationships are summarized in the diagram below, which shows how each tool, specification, or group fits into the OpenAPI ecosystem.

Each of these provides features and functions important to the API community.

OpenAPI Specification

The OpenAPI Specification is the center of the OAI and the focus of our efforts to support the API community. OpenAPI is the most widely used API description language in the API ecosystem, with arguably the longest legacy, and supports the publication and consumption of an innumerable number of APIs throughout the API lifecycle.

The OpenAPI Specification is undergoing active development with support from dedicated volunteers, with a new major version coming soon focused on the semantic improvement of the specification and supporting AI use cases. The OAI is constantly evaluating how we can improve the development of the standard, and provide support for tooling makers who are implementing the specification.

OpenAPI is currently at version 3.1.1, with multiple versions planned to harmonize the features of the Specification in readiness for version 4.0.0, our next major version codenamed “Moonwalk”. You can read more about version 3.1.1 on our standards site and discover the goals of Moonwalk on our blog. We also released version 3.0.4 in 2024, again in an effort to harmonize guidance across different versions.

Arazzo Specification

The OpenAPI Specification was created to describe a single API and its supported operations. The API ecosystem has, however, grown significantly more complex as it has expanded, with a need to invoke multiple API operations across different API providers to complete a business operation. This growth in the interdependency of API operations has created a need for sequences of API calls to be described programmatically, which is why the Workflows Special Interest Group created the Arazzo Specification.

Arazzo is a description language that can reference multiple APIs, each described with an OpenAPI description or another Arazzo description, that provides API consumers with a rich view of complex, multistep workflows. Arazzo supports describing dynamic values, allowing API providers or API marketplaces to indicate how API operations relate to each other and the output and inputs that can be carried between each step. When supported by appropriate tooling this can significantly accelerate implementation time for API consumers and ensure they can handle sequences of API requests more accurately.

Arazzo is currently at version 1.0.0. You can read more about the Specification on our standards website.

Overlay Specification

The OpenAPI and Arazzo Specifications provide the backbone of the OAI, with description languages aimed at supporting use cases across the API ecosystem. OAI is also creating complementary specifications that help API providers and consumers publish and consistently work with OpenAPI descriptions.

An example of these efforts is the Overlay Specification, which is now at version 1.0.0. The Overlay Specification is intended to provide a consistent and deterministic way of applying updates to an OpenAPI description document. Example use cases include supporting multi-language API descriptions by using Overlays to contain language translations and including configuration information for different deployment environments in an OpenAPI description document.

OAS Comply

OAS Comply is an effort to develop tools to support tooling makers in implementing the OpenAPI Specification, with the potential to expand in the future to include the Arazzo Specification. The OASComply project was started in 2023 and was instrumental in understanding where the 3.0 and 3.1 specifications needed clarification.

The discoveries provided by OASComply motivated much of the work in the Open Specification 3.0.4 and 3.1.1 releases, as well as making compliance testability a major focus for Moonwalk. OASComply itself is on hold while we proceed with Moonwalk and figure out how compliance testability work might fit into our version 3 standards.

Special Interest Groups

Finally, OAI has Special Interest Groups that are focal points in evolving specific use cases across industries, verticals, or technology requirements. SIGs are an important means for channeling support for new ideas and initiatives, and it speaks volumes that the efforts to create Arazzo, Overlay, and Moonwalk are focused through SIGs.

The Future of the OpenAPI Initiative

The evolution of the OpenAPI Initiative has been largely organic and relied upon the endeavors of many dedicated volunteers. The members of the OpenAPI community have investigated, researched, discussed, and authored for thousands of hours to reach this point in the evolution of the OpenAPI Initiative.

Our next steps as an organization include:

• Producing new versions of OpenAPI, including our next major version.
• Maturing Arazzo and Overlay and helping tooling makers to support the specifications.
• Expanding our support for both OpenAPI members and the community with investments in training, education, and certification.

If you are interested in helping develop the most important API description language on the Internet there is a huge opportunity for you. Join our Slack community to find out more.

Author: Chris Wood

AVAP Framework has just joined OpenAPI as a member!

We are thrilled to announce that AVAP Framework, a cutting-edge API Lifecycle Management Platform, has officially joined the OpenAPI Initiative (OAI) as a proud member! This milestone reflects our commitment to innovation, collaboration, and advancing open standards in the API ecosystem.

What Is AVAP Framework?

AVAP Framework is a comprehensive suite of tools and services designed to streamline the entire API lifecycle—from design and development to deployment, maintenance, and beyond. At its heart is AVAP (Advanced Virtual API Programming), a specialized programming language tailored for creating virtual APIs that adapt seamlessly to evolving business and technology needs.

Central to AVAP Framework is Brunix, our AI-powered engine. Brunix optimizes processes, predicts solutions, and ensures that APIs are scalable, secure, and efficient across diverse environments. AVAP Framework’s universal compatibility ensures seamless integration with other technologies, enabling businesses to build flexible, resource-efficient, and future-ready APIs.

By joining the OpenAPI Initiative, AVAP Framework is aligning with the industry’s leading community focused on developing and promoting open standards for API design. Through this collaboration, we aim to contribute our expertise in virtual API programming, AI-driven innovations, and API lifecycle management to the evolution of the OpenAPI Specification (OAS).

Raúl Nogales, Founder & CEO of AVAP, will serve as our representative in the OAI. With his extensive experience in API innovation and technology, we are confident that AVAP Framework will add significant value to the OpenAPI ecosystem.

OpenAPI Resources

Want to become a member of the OpenAPI Initiative? Find more information here: https://www.openapis.org/membership/join 

To learn more about participating in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

• OpenAPI Specification LinkedIn Page
• OpenAPI Specification Twitter
• OpenAPI Specification GitHub – Get started immediately!
• Share your OpenAPI Spec v3 Implementations

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor neutral description format. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

About Linux Foundation

Founded in 2000, the Linux Foundation is supported by more than 1,000 members and is the world’s leading home for collaboration on open source software, open standards, open data, and open hardware. Linux Foundation projects like Linux, Kubernetes, Node.js and more are considered critical to the development of the world’s most important infrastructure. Its development methodology leverages established best practices and addresses the needs of contributors, users and solution providers to create sustainable models for open collaboration. For more information, please visit us at linuxfoundation.org.

Buy-now, Pay-later – An Example Use Case for the Arazzo Specification

The continued growth of the API economy presents us with an ever-increasing number of APIs we use in building systems and doing business. With this volume of APIs comes complexity. We find ourselves calling multiple APIs, from the same provider and across multiple API providers, to execute a given business function. This growth in the interdependency of API operations has created a need for sequences of API calls to be described programmatically , which is why our Workflows Special Interest Group created the Arazzo Specification

Arazzo is a description language that can reference multiple APIs, each described with an OpenAPI description or another Arazzo description, that provides API consumers with a rich view of complex, multistep workflows. Arazzo supports describing dynamic values, allowing API providers or API marketplaces to indicate how API operations relate to each other and the output and inputs that can be carried between each step. When supported by appropriate tooling this can significantly accelerate implementation time for API consumers and ensure they can handle sequences of API requests more accurately.

The use case for an Arazzo description can be applied across almost any industry or vertical. Financial services APIs, for example, demonstrate how such orchestration needs have grown across an ecosystem, where examples of APIs that need to be called in sequence are common for operations like account opening and payments. Buy-now, pay-later (BNPL) is one such use case, as this generally requires multiple API calls to secure a loan at the point of purchase. The sequence of steps can be generalized as follows:

1. Product Eligibility Check: Customers select the BNPL option at checkout. An API call is made to correlate the items in the customer’s basket with BNPL finance options. The BNPL options are then displayed to the customer.
2. Customer Selection: The customer chooses an offer from the list displayed. An API call is then made to retrieve terms and conditions.
3. Eligibility Verification: Once the customer has selected the product and accepted the terms and conditions, an eligibility/credit check may be required, which may involve enrolling the customer on the BNPL platform.
4. Initiate BNPL Transaction: With product selection and eligibility complete the BNPL transaction then takes place. An API call is made from the checkout provider to the BNPL platform with the order details and customer information.
5. Authentication & Authorization: The customer may then be required to authenticate themselves at the BNPL provider and authorize the transaction. This may happen through redirection to the BNPL platform.
6. Finalize Payment Plan: Once the transaction is validated and the customer authenticated, the checkout will retrieve the finalized details of the loan including the payment schedule, interest rates, and so on.
7. Order Confirmation: Confirmation of the BNPL transaction and payment plan acceptance is then signaled through an API call.
8. Update Order Status: With financing secured the eCommerce platform will proceed with fulfillment and confirm fulfillment back to the BNPL platform.
9. Payment Updates: Optionally, for subscription-based products, there may be ongoing updates over callbacks or webhooks from the BNPL platform to the eCommerce platform, with events such as missed payments or loan completion.

The sequence diagram below reflects the steps 1 to 8 described above:

This example reflects how composable software services have become and how we can tailor our platforms based on the myriad of available API providers. The steps and sequence diagram show the complexity that typifies such business flows, especially in eCommerce and is exactly the scenario Arazzo looks to address. An Arazzo description is designed to help platform providers describe flows across their APIs and take the guesswork out of stitching them together. This is of significant benefit for API consumers as they get a structured, versioned description of the required steps that they can use to implement their integration. This gives API consumers a reference point they can rely on to ensure their workflow is implemented as expected and working correctly.

To help bring this example to life, we’ve created a BNPL Arazzo description and OpenAPI description in the Arazzo Specification repository.

The BNPL description includes the inputs to the sequence described above, defined as a Workflow Object:

- workflowId: ApplyForLoanAtCheckout
  summary: Apply for a loan at checkout using a BNPL platform
  description: Describes the steps to secure a loan at checkout from a BNPL platform. It is a multistep process that requires multiple API calls across several API providers to be completed successfully.
  inputs:
    type: object
    required:
      - customer
      - products
    properties:
      customer:
        # Customer properties
      products:
        # Product properties

The Workflow Object defines the parameters required to initiate the flow which, in this case, include the parameters to make the first API call to check product eligibility and a later step to check customer eligibility for the loan. The inputs to this workflow are:

• The customer details, which can be the full details or a URL that indicates an existing customer resource if the customer is already enrolled on the BNPL platform.
• An array of products, used to assess the customer basket qualification for a checkout loan at the BNPL platform.

All other arguments in the sequence are then elicited using response properties from each API call. These are represented by Step Objects that define the sequence, the conditions that indicate a step has been successful and pointers to dynamic values that can be passed between steps.

For example, the first step in our BNPL use case was to check products in the customer’s basket that were eligible for a loan. This is encapsulated in the following Step Object:

- stepId: checkLoanCanBeProvided
  description: |
    Call the BNPL API to filter the basket for products qualifying for checkout loans. Pass in the array of products from the workflow input as the payload for the API call.

    Act on the response payload:

    - If a list of qualifying products is returned then submit customer choices.
    - If the list of qualifying products is empty then end the workflow
  operationId: findEligibleProducts
  requestBody:
    contentType: application/json
    payload: |
      {
        "customer": "{$inputs.customer}",
        "products": "{$inputs.products}"
      }
  successCriteria:
    - condition: $statusCode == 200
  onSuccess:
    - name: existingCustomerNotEligible
      type: end
      criteria:
        - condition: $statusCode == 200
        - condition: $response.body.existingCustomerNotEligible == false
    - name: qualifyingProductsFound
      type: goto
      stepId: getCustomerTermsAndConditions
      criteria:
        - condition: $statusCode == 200
        - context: $response.body
          type: jsonpath
          condition: $[?count(@.products) > 0]
    - name: qualifyingProductsNotFound
      type: end
      criteria:
        - condition: $statusCode == 200
        - context: $response.body
          type: jsonpath
          condition: $[?count(@.products) == 0]
  outputs:
    eligibilityCheckRequired: $response.body.eligibilityCheckRequired
    eligibleProducts: $response.body.products
    totalLoanAmount: $response.body.totalAmount

The Step object definition provides:

• The unique identifier for the definition.
• A reference to the operationId value of the associated Operation in the target OpenAPI description.
• A Request Body Object to describe the inputs to the step, which can include external inputs defined in the Workflow object. In this case, we reference the products in the customer’s basket and their customer details.
• The success criteria that define whether the step was successful. This is expressed through one or more conditions evaluated using HTTP return codes and properties of the response body, referenced using JSON Path.
• Directives on what to do if the API call was successful. In this case, if zero qualifying products are returned the workflow ends.
• Outputs from the step that allows dynamic values to be passed to subsequent steps. In our example, these include the filtered product details that can be shown to the customer to indicate which products are eligible for a BNPL loan and whether a customer eligibility check is required.

The Arazzo Specification is therefore geared towards providing a simple, declarative approach to describe a sequence of API calls to provide flexibility for the API provider and ease of use for the API consumer. You can follow our full example using the links above to discover more about how the Arazzo Specification can help you describe complex, multistep sequences of API calls.

If you are interested in learning more about Arazzo please read the specification, visit our discussions or join us on Slack. Feedback on the Arazzo Specification is most welcome!