Skip to main content

OpenAPI Spec

Meeting Orchestration Needs with Arazzo

By Announcement, Blog

Today we are delighted to announce the release of Arazzo, a new OpenAPI Initiative specification designed to describe sequences of API calls to meet the orchestration needs of API providers and consumers.

In a digital economy increasingly powered by APIs there is a need to accurately reflect the increasing complexity of the integration required to do business. Organizations calling multiple APIs to execute business flows and functions, sometimes across multiple service providers, require guidance and support to correctly implement sequences of API calls, with cognizance of success and failure at each step.

The Workflows Special Interest Group (SIG), part of the OpenAPI Initiative umbrella of specifications, has created the first release of the Arazzo Specification to meet the increasingly complex integration needs. Arazzo will allow API and integration service providers to build on top of OpenAPI Specification, providing information on sequences of API calls that comprise a flow or function.

Using Arazzo API providers can:

  • Link multiple operations, described through OpenAPI or other Arazzo descriptions, into one sequence of activities.
  • Provide criteria that describe success or failure based on the responses received from the APIs that API consumers call.
  • Implement variables that can carry dynamic variables from one API call to another, ensuring that data is successfully carried, as needed, through the context of the described sequence.

Like the OpenAPI Specification, the goal is to create a rich description language that can be used both for documentation and to automatically create integration code from machine-readable sources.

Frank Kilcommins, Principal API Evangelist at SmartBear and member of the Workflow SIG team, describes Arazzo as:

“An important milestone on the path to improved API maturity across the industry. By providing deterministic recipes for value-based usage of APIs, the Arazzo Specification, through its human- and machine-readable attributes, acts as living API documentation, reducing dependence on out-of-band onboarding guides. It ensures assertable qualities for API providers and regulatory stakeholders across the API lifecycle, while also empowering tooling vendors to craft the next wave of SDKs and code generators.

The Arazzo Specification enables human API consumers to better understand how to use and combine APIs, focusing on their jobs to be done, thus reducing their mean time to integration. Concurrently, it offers a consistent and interoperable mechanism for the new wave of AI consumers to achieve expected API outcomes first and every time.”

Arazzo will evolve as more organizations and tooling makers implement the specification. Please visit the specification page and repository, or join our Slack channel for more information.

OpenAPI Moonwalk 2024

By Announcement, Blog, News

An astronaut plants a flag with an OpenAPI logo on the moon.What comes next for the OpenAPI Specification? How will v4 improve on the success of OpenAPI v3? What can the spec help solve problems in the context of AI and LLMs?

As 2023 comes to a close, answers to these questions are beginning to take shape. With an aggressive goal of launching v4 “Moonwalk” by the end of 2024, it is going to be an exciting year.

Because there is so much work to be done, it was necessary to establish some guiding principles. After reviewing the major proposals and discussions of the last year, these are semantics, signatures, inclusion, organization, upgrading, and their order is important:

    1. 🌖 Semantics provide purpose. It is not sufficient to describe the mechanics of an API without also describing its semantics, whether the consumer is a human or an AI. Semantics join the what (… does this do?) and the why (… does this matter?) to the how (… does this work?).

      OpenAPI has helped people build better APIs faster, and the ecosystem of tooling continues to deliver more value year after year. What is new today in 2023 is the rise of a new kind of API consumer—generative AI. LLMs can process OpenAPI descriptions and then use that API to solve problems. With generative AI’s ability to understand natural language, OpenAPI can help bring the power of APIs to non-developers with a level of accessibility never seen before. To fully realize this potential, API producers should decorate their mechanical descriptions of HTTP requests with details that convey the meaning and purpose of those API operations. This, in turn, helps both people and LLMs to achieve better results.

      To say this another way, people have been using squishy, natural language to talk to each other for centuries, and we’ve used crunchy, programming languages to talk to machines for decades. LLMs bridge the squishy and the crunchy worlds, which means that a huge number of people can use APIs who could not before.

      Regardless of your opinion of generative AI, from over-hyped to world-changing, we can expect that many people will be using OpenAPI to drive AI-based API consumers. If OpenAPI does not step up to address the needs of that community, they will find alternatives.

    2. 🌒 Signature please! An API represents a set of functions, each of which describes a client-oriented purpose. A function is identifiable by its signature, which correlates to a set of HTTP interactions. Moonwalk places this concept at its center.

      Any HTTP API is always a means to some end. API consumers prefer to reuse existing functionality, and ideally they can learn about that functionality in terms that are most natural to them. That a PUT/PATCH/DELETE returns a 200 or a 204 is an implementation detail that pales in comparison to the function it performs for the client. Today there are limited ways to express the signature of an API function in OpenAPI. A pathItem can’t use query parameters to distinguish operations. There can only be one operation per HTTP method. These are artificial constraints on the signature of the API functions due to the lack of a formal definition of the unique signature. Past efforts in OpenAPI have focused on enabling developers to describe HTTP APIs. This reprioritizes them so that developers can use OpenAPI to define API functions with unique signatures that then map each signature to HTTP mechanics.

    1. 🌕 Inclusion needs a big tent: Moonwalk aspires to describe all HTTP-based APIs. While it remains neutral on the design aspects of HTTP APIs, it recognizes the importance of having different design styles and opinions.

      Moonwalk should be able to describe the HTTP APIs that developers may already have as well as to design the APIs they may want to build. It should be able to accurately map the signature of an API function to an actual instance of an HTTP request and response provided by the API. Moonwalk does prefer resource-oriented API styles due to their overwhelming popularity, but it should be possible to describe purely RPC APIs, even when those API signatures are distinguished via HTTP header values or request body values.

    1. 🌗 Organization through separation of concerns. For example, the changing shape of an API should move independently of API deployments. API deployments may be secured with different security schemes. API functions’ signatures should not be tightly coupled to content schema formats.

      To support the growing customer base with diverse needs, the feature count will undoubtedly grow, introducing more complexity. To counterbalance this, we will apply more rigor to the modularization of different aspects of the API description. We will strive to eliminate ambiguity where it currently exists and leverage existing standards to minimize unnecessary novelty. Our goal is to provide a better experience for API description consumers, authors and tooling providers.

    1. 🌑 Mechanical upgrading. An important principle of OpenAPI v3 was that it offered a direct upgrade path from v2. Moonwalk carries this forward, which means that it must again be possible to mechanically upgrade to Moonwalk from v3 (and by extension, v2).

Important open source projects like OpenAPI depend on contributions from many people. If you are as excited as we are about the ideas above or about the opportunity to leverage AI to help APIs be used by more people, then please get involved! A great way to start is to join our weekly calls on Thursdays (details), and anyone who wants to join is welcome!


OpenAPI Specification 3.1.0 Released

By Announcement, Blog

OpenAPI developer community and JSON Schema community work together to build upgrade that supports 100% compatibility with the latest draft of JSON Schema

SAN FRANCISCO – February 18, 2021 – The OpenAPI Initiative, the consortium of forward-looking industry experts focused on creating, evolving and promoting the OpenAPI Specification (OAS), a vendor-neutral, open description format for HTTP (including RESTful) APIs, announced today that the OpenAPI Specification 3.1.0 has been released. This new version now supports 100% compatibility with the latest draft (2020-12) of JSON Schema.

Along with this release, the OpenAPI Initiative has sponsored the creation of new documentation to make it easier to understand the structure of the specification and its benefits. It is available here: 

The OpenAPI Specification is a broadly adopted industry standard for describing modern APIs. It defines a standard, programming language-agnostic interface description for HTTP APIs which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. 

The OpenAPI Specification (OAS) is used by organizations worldwide including Atlassian, Bloomberg, eBay, Google, IBM, Microsoft, Oracle, Postman, SAP, SmartBear, Vonage, and many more.

“The benefits of using the OpenAPI Specification are broadly applicable, ranging from API lifecycle management, to documentation, to security, to microservices development and much, much more,” said Marsh Gardiner, Product Manager, Google, and Technical Steering Committee, OpenAPI Initiative. “Great care was taken in evolving to version 3.1.0 to ensure it is an incremental upgrade for existing users, while also making it an excellent candidate for immediate evaluation and adoption in corporate environments. We extend our heartfelt gratitude to the diverse group of contributors for all their exceptional skills and effort on our latest achievement.”

“The mismatch between OpenAPI JSON Schema-like structures and JSON Schema itself has long been a problem for users and implementers. Full alignment of OpenAPI 3.1.0 with JSON Schema draft 2020-12 will not only save users much pain, but also ushers in a new standardised approach to schema extensions,” said Ben Hutton, JSON Schema project lead. “We’ve spent the last few years (and release) making sure we can clearly hear and understand issues the community faces. With our time limited volunteer based effort, not only have we fixed many pain points and added new features, but JSON Schema vocabularies allows for standards to be defined which cater for use cases beyond validation, such as the generation of code, UI, and documentation.

On Day One of JSON Schema draft 2020-12 being released, two implementations were ready. It’s humbling to work with such an experienced and skilled team.”

While JSON Schema is still technically a “draft” specification, draft 2020-12 sets a new stable foundation on which 3rd parties can build standardised extensions. The JSON Schema team do not foresee any major changes to the approach of the extension system, like dialects and vocabularies. However, the utility may be improved as feedback is received.

JSON Schema website: 

JSON Schema Open Collective: 

JSON Schema Twitter:

Major Changes in OpenAPI Specification 3.1.0

  • JSON Schema vocabularies alignment
  • New top-level element for describing Webhooks that are registered and managed out of band
  • Support for identifying API licenses using the standard SPDX identifier
  • PathItems object is now optional to make it simpler to create reusable libraries of components. Reusable PathItems can be described in the components object. There is also support for describing APIs secured using client certificates.

Full OpenAPI Specification 3.1.0 release notes are available here:

A Note on Semantic Versioning

The OpenAPI Initiative had adopted semantic versioning to communicate the significance of changes in software upgrades. Semantic versioning is a popular numbering methodology where minor version updates indicate changes to software are backward compatible, whereas major updates are not. Technically, using semantic versioning with the new full alignment with JSON Schema would require this change to be denoted as 4.0.0. However, this update to OpenAPI important improvements, specifically the alignment with JSON Schema, but to force it into a major release numbering would have created a mismatch of expectations.

Special Thanks

A special callout to Henry Andrews, Phil Sturgeon, and Ben Hutton for all their work, support and patient explanations they have provided to better align JSON Schema and the OpenAPI Specification. Many thanks to Lorna Mitchell for driving the Webhooks effort, using our new proposal process. And thanks to the many, many open source developers involved worldwide.

OpenAPI Resources

To learn more about participate in the evolution of the OpenAPI Specification:

●   Become a Member

●   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

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

From APIDays Paris: OpenAPI 3.1 Coming Soon

By Blog

Originally posted in the LORNAJANE Blog – Thank you, Lorna!

What’s New in OpenAPI 3.1

With OpenAPI 3.1 coming “soon”, I gave a talk at APIDays Paris about what to expect. But I’m a great fan of the written word as reference so here’s a written recap of what’s in the next OpenAPI release.

Top features:
– Compatible with JSON Schema 2020-12
– Webhook support
– Many other minor improvements

Version Numbering

As of OpenAPI 3.1, the OpenAPI project doesn’t follow semantic versioning. That sounds like a totally irresponsible decision but it actually makes some sense for a standard where every API description clearly states the version of OpenAPI it relates to. Also, they don’t let me make the rules, sadly! It’s not a major release, but some things had to be undone and redone to accommodate JSON Schema.

JSON Schema 2020-12

This is really big news, so much of OpenAPI is used alongside JSON Schema and the 3.0 release was quite a long time ago and didn’t quite accommodate everything that makes sense today in JSON Schema. This post won’t cover what’s new in JSON Schema itself but I’ll try to round up the main points from the perspective of OpenAPI users.

First of all: types can now be arrays of types, so something could be of type [string,number]. The available types also include null, so more common will be [string, ‘null’]. This does impact on existing OpenAPI documents as from 3.1, the nullable keyword is removed – use the array of types and one of the types is null.

  - name: friendly-label
    in: query
        - string
        - 'null'

OpenAPI 3.1 is getting support for the examples keyword within a schema, allowing an array of examples. Often the array only contains one element though. The original singular example keyword is still valid, but examples is recommended and if both are present then examples is preferred. Be aware that this array of values is in contrast with the other use of examples in OpenAPI, in a MediaType content object, where the examples field is a map with string keys. Confused? So are we. There is a post all about OpenAPI examples from Phil that explains it all!

A couple of other things are coming in from JSON Schema into the OpenAPI schemas. First of all: arbitrary keys are allowed in a schema; OpenAPI has relaxed its constraints on which fields can appear where to accommodate JSON Schema format objects. Also it’s possible to $ref to an object, then put keys alongside it which are considered in addition to what is defined in the component.

      $ref: '#/components/schemas/style'
        - hue

None of these changes are huge, but having the ability to use JSON Schema within OpenAPI is brilliant for anyone wanting to use the two together so to have this commitment to supporting the ever-improving JSON Schema is excellent news.


I’m totally biased because I proposed this feature. I couldn’t believe that OpenAPI didn’t already support this common use case and it took time to realise that it wasn’t that I didn’t understand how to do something – that thing really was outside what OpenAPI 3.0 expected APIs to describe.

OpenAPI 3.0 does have support for callbacks so if the user should make an API call, supply a URL, and stand by for incoming HTTP requests to that URL as a result, that’s already supported. This is ideal when an endpoint asynchronously returns data, or for some situations where an API call “subscribes” to an event and gives a URL to send things to.

OpenAPI 3.1 goes a step further and allows webhooks which are incoming HTTP requests that are in response to some external event or stimulus. A great example would be if you’ve ever linked anything to a GitHub push event, or an incoming order/payment/message (and I’ve been working for a communications company for a few years, so you can immediately understand how I got entangled in this). The webhooks are described a LOT like the existing callbacks are, and indeed both are much like the existing request descriptions, so I hope this change will be easily adopted by everyone who has a two-way API like this.

The new webhooks keyword is a top-level element, alongside paths. There are also changes to the required fields: OpenAPI 3.0 required openapi and info and paths but in OpenAPI 3.1 only openapi and info are always required, but the document must also contain at least one of paths or webhooks or components. This is brilliant because it allows API descriptions to contain only outgoing API calls, only incoming webhooks, only components that might be referred to by other documents, or any combination or all of these – and still be valid in its own right.

Anyway, back to the webhooks.

      operationId: inbound-sms
          application/json: ...
      responses: ...

Within the webhooks section, each incoming “thing” has a key (such as inbound-sms in the example above) and then it goes on just … looking like a pathItem, because that is all it is. You don’t need to specify the URL path that the webhook will come in on (often the user can nominate that anyway), just explain what will arrive and you are done. Oh and related to this: pathItem is now allowed in the components section and you can $ref to a pathItem from either a path or a callback or a webhook.

Fancy a sneak preview of what the webhooks will look like when the tools get support for it? Redoc already has preview support if you use x-webhooks in your 3.0 OpenAPI documents! I mean, it just looks like really competent API documentation but that’s what we need here 🙂

A note about webhooks and callbacks. Quite a few endpoints could be considered as either a webhook or a callback, and I have already started getting questions about which to use. It probably doesn’t matter but if there is no preceeding API call that the callback is a response to, then it’s definitely a webhook. Where there is some previous API call with a URL, then it’s probably up to you how you want it to work. For example at Vonage the configuration for where to send events for an incoming Message is at the application level, do you do that with the Application API – but I’d rather have the API description with the incoming Message webhook detail shown next to the send Message API call, in the same document, tagged and grouped together in the Message API description. The webhooks keyword gives you the flexbility to approach this as you will.

Small But Perfectly-Formed Upgrades

There are so many small things that have been added in OpenAPI 3.1 but I’m picking my favourites to include! As with every *.1 release, there are things that seemed like a good idea for the *.0 release that can now be tidied up a little now we’ve all tried them out in anger, it’s a good thin.

I’ll start with the one I want to implement immediately (or as soon as the tools allow): $ref can now have summary and description as siblings, and they override any existing fields on the referred-to component.

        - $ref: '#/components/parameters/item'
          description: The specific item in question

There are a few minor things in the info section as well:

  • Inside info, you can now have summary alongside the description field. Both are optional – title is still required.
  • In the license object you can use an SPDX code in the new identifier field instead of a url alongside the required name field if you prefer

Finally, paths are no longer required to have responses field for every endpoint. This is useful when an OpenAPI document is under construction because it means that it will validate even when you’re still only sketching out the endpoints that the API definition will include.

Further Reading

I’ll share links to my talk when the recording is published (the slides are on notist but keep up with the current status of the OpenAPI 3.1 release and read the (much better) changelogs on the project itself for more information

Three common scenarios for leveraging the OpenAPI Specification

By Blog

This article is a short preview of the forthcoming talk “Designing APIs with the OpenAPI Specification” to be delivered at Codemotion conference, Madrid, Spain on November, 24th.

We, as developers, are surrounded by powerful and amazing APIs. Just finding the time to integrate the interesting services to enhance our product could be a daunting task just because time is the scarcest resource we have as developers.

API integration is a recurrent pain for developers because frequently we feel like frustrated plumbers trying to connect pipes of different sizes and materials, forced to create custom adapters and junctions over and over again. You already know the feeling, don’t you?

We are already living in fast times where the API-economy drives much of technology innovation. Platforms like Amazon, Paypal, Stripe, Heroku, and Google Maps to cite a few, are good examples of successful platforms and products that are leaders in their respective markets, creating ecosystems around them. If you own the ecosystem, you win the game. APIs have a story to tell: good APIs – easy to consume by third-parties  – can help further adoption. We, the developers as API consumers, decide in many occasion which APIs succeed and which ones are not used anymore.

In this context of rapid innovation, API discovery, and easy integration is key for every new service on town. In this field is where the OpenAPI Spec can help the most.

OpenAPI Spec provides a solid standard for describing interoperable REST APIs based on resources and HTTP. This description is useful for two types of audiences: humans and machines.

  • Humans use the specification as a source of API documentation, examples and as a guide to try out and understand the capabilities of the API. Easy of use is the key factor here for succeed.
  • Machines use the specification for creating code able to talk the service protocol in the language of your developments. Reducing in this way the hard plumbing work described before and minimizing the cost and needs for platform specific SDKs.

In my experience, there are three major use cases for using OpenAPI Spec on your API project: legacy APIs, contact-first driven, and server-first driven. Let’s review them one by one.

1. Legacy API

The first scenario covers services and APIs that are already in production. Adding an OpenAPI document will formally capture the signature of the API in a standardized way. Therefore, consumers can use this contract as documentation to easily integrate with your API.


As long as you are using HTTP or HTTPS with JSON or XML encoding, it doesn’t matter what language or framework you choosed for the implementation: you have an interoperable API awaiting to be discovered by the world.


The best thing here that surprise many people is: you don’t have to change a single bit of your running API or service. The metadata provided by the OpenAPI Spec is a contract stored in a self-contained file (YAML or JSON) you can share offline (as a file) or publish in any web server.

Adding the contract will not change a bit of your legacy implementation, but will help developers out there to try and consume your API.

2. Contract-first driven API

To speed up developments, it is frequent to work in parallel in two teams: back-end and front-end. Both can build their stuff in parallel if they agreed to an API contract. Front-end people usually create and use mock-ups of the contract to be able to work without having to be waiting for the back-end to be ready.

OpenAPI and related tools here provide good tooling for this task. The OpenAPI contract can be edited and validated with no language or implementation assumptions (making the API really very, very interoperable).

Then, using OAS code-gen tools both teams can generate skeletons for the server-side and proxies for the frontend in any supported language or platform.

I recomend this way of working when the main functionality is clear enough to be able to design the contract up-front.

In the long-term you will maintain and evolve the contract in a planned manner. So this is the recommended approach in the long-run for a high quality API contract.

Note: a clear versioning strategy is important in order not to break old clients when a new version arrive.

3. Server-first driven API

In other type of projects, developers can decide to build their API directly on their favourite language and platform and derive the API contract later, as a direct consequence of the running implementation. This scenario is also supported by the OpenAPI Spec. An specific library for the target language is employed. Using reflection techniques and metadata to discover services, types, parameters directly inspecting the source code to automatically generate an OAS compliant spec on the fly.

This approach has some advantages:

  • Auto-generated documentation and contract.
  • Contract is always in sync with service implementation.
  • Agility in server-side development.

Major cons of the approach:

  • Be diligent when evolving the service, you could inadvertently break existing clients.
  • Derived contract could lack of simplicity or UX (if compared with a contract first). What is optimized for automation could be confusing for humans: design for humans.

NOTE: I recommend the server-first approach when the requirements and design is changing fast and your team is iterating to find the right contract design. Being not yet in production, this will alleviate breaking the clients. In any case, fully review your final API contract and refactor for a better UX before launching it.


OpenAPI provides an interoperable way of describing an API:

  • formally enough to be consumed by machines and
  • KISS enough to be used by developers to document and learn the API.

The three scenarios described provide flexibility to fit with different project needs. Honestly, I think this is the main feature of the OpenAPI precursor, known as Swagger, got right from the very beginning: adapting well to very different development scenarios and different project development stages.

Software engineering is still a young discipline if compared with plumbing or electrical engineering. We need standards that helps us to deal with and automate repetitive tasks. That’s why, I think whatever you are, a machine or a human, exposing APIs with the OpenAPI Spec is a good thing to have in your public API!

If you liked this post and want to know more about it, join my talk at Codemotion in Madrid at November 24th and let’s deep dive on it!

About the author


Pedro J. Molina

Pedro J. Molina holds a PhD. in Computer Sciences from the Technical University of Valencia. After working in different product companies related to Modeling and Code Generation he set up a startup called Metadev with focus on tooling for microservices and cloud development. Twitter: @pmolinam