overlay – OpenAPI Initiative

Feb 10

OpenAPI Initiative Newsletter – February 2026

By Chris Wood Blog

Welcome to the OpenAPI Initiative (OAI) February 2026 newsletter!

This is our first newsletter of 2026, and there is already plenty to share from the OAI community.

Initiative News

We’ve made a great start to 2026 in the Overlay world with completion of version 1.1.0 of the Overlay Specification. Version 1.1.0 brings several new features, including a new copy property for the Action Object, which can be used to copy or move an element in the OpenAPI document. This property is great for operations where you may already have a source-of-truth embedded in part of your API description, and want to use it across all operations. For example, you might implement a default Response Object and wish to copy it to all Operation responses to give more consistency for API consumers.

Other improvements include the ability to update primitive values – strings, integers, and so on – rather than updating the parent object, making Overlay documents more concise and easier to manage. The specification has also been updated for full compliance with RFC 9535, to ensure tooling makers are creating Overlay tools through guidance that is fully compatible with the latest JSONPath standards.

To learn more about upgrading, use this helpful guide. As always, new versions of our specifications are nothing without our community of contributors, so a huge thanks to Vincent Biret, Lorna Mitchell, Ralf Handl, and Michael Kistler for contributions, reviews, and support.

The Moonwalk Special Interest Group (SIG) has also entered 2026 with a new focus. The SIG will continue to explore concepts that go beyond the current OpenAPI v3 Specification, with a particular focus in the first six months of 2026 on how OpenAPI relates to large language models (LLMs) as a new class of API clients. The groups aims to investigate what additional metadata or structural information might be needed in OpenAPI documents to make them more “agent-ready” for LLM use, including capability discovery and intent signaling. Several open questions are being posed, including around surfacing capabilities, grouping functionality for agents, and optimizing descriptions for LLM-based workflows. You can find the full scope of this initiative here.

As always, initiatives as important as this do not create themselves (whatever the capabilities of AI), so the Moonwalk SIG is looking for new contributors and hosts to help in this important work. The Moonwalk SIG is every Tuesday at 1700 GMT / 0900 PST, with the agenda for each meeting published on the GitHub Discussions link above.

Building on the success of v3.2, and the continued great feedback we are getting from the community, we are looking to enhance our coverage of important API security specification in future versions, including the FAPI Security Profile, which is commonly used in open banking and open finance, and AuthZEN. We also have the Industry Standards Special Interest Group, which looks specifically at industry collaboration and how OAI specifications can meet the needs of API providers across a range of verticals. If you are interested in taking part the Industry Standards SIG to help foster collaboration across industries join the channel in Slack. You can also read the draft work plan for 2026 here to learn more about the goals of the SIG. SIG meetings are on Mondays at 1730 GMT / 0930 PST and are bi-weekly.

2026 promises to be another exciting year for OAI, with the growing opportunity of specification updates, collaboration with industry verticals and software foundations who rely on OAI specifications, and the exploration into greater compatibility with AI and agentic tooling. We are always on the lookout for new members, so if you are thinking of getting involved, becoming a member is one way of contributing to the work OAI does if you are unable to contribute through specification maintenance or taking part in SIGs. Head over to the membership page on our website to find out more.

Events News

The end of last year saw our final event of the year, the Future of Software Technologies (FOST) – forever known as Apidays – Paris conference. The event attracted a huge number of delegates, speakers, and exhibiters, with APIs still obviously the key theme, but the role of AI, standards such as MCP, AI and agentic security, and the intersection between agents and APIs being key talking points throughout.

OAI hosted our own sub-conference, hosted by Erik Wilde and Frank Kilcommins with a stellar line-up from the OAI community and huge interest from the community with a packed conference room for most sessions. We saw speakers such as Emmanuel Paraskakis talk about API design in the context of AI-based design workflows, Marjukka Niinioja describe how to embed OpenAPI into daily workflows using Lean principles to eliminate API delivery waste, and Dimitri van Hees give an overview of the Dutch Government API developer portal and their OpenAPI-first approach for public sector APIs. Frank and Chris Wood also talked on the Travel Tech sub-conference and discussed Arazzo in the context of travel API workflows.

Frank Kilcommins at Apidays Paris 2026 Talking Arazzo and AI Agents

This year we’ll be keeping our focus on our successful partnership with FOST whilst continuing to develop new relationships with other conferences. To that end our first conference of the year is the OpenAPI Summit at DeveloperWeek, San Jose, with a full day of speakers focusing on all things OAI and AI. We have Henry Andrews providing an overview of v3.2 of OpenAPI, Sumit Amar focusing on using AI tools like Copilot and Cursor to automate API design, development, testing, and observability, and Kuldeepak Angrish and Budha Bhattacharya discussing how API standards and governance create the foundation for AI-readiness before implementing LLMs or MCP. Head over to our dedicated Events site for more details, including the sign-up link for Developer Week.

We also have Apidays Singapore, New York, and Munich – and of course Paris – already lined-up for this year. Stay tuned the newsletter and updated on our Events site and LinkedIn page for details as they are finalized!

Ecosystem Spotlight: Jentic AI-Readiness Scorecard

Our Ecosystem Spotlight focuses on the work of OAI members and the OAI community in general in using OAI specifications in tooling, products, and experiences. The Ecosystem Spotlight in this newsletter is provided by Jentic, an OAI member who leverages both OpenAPI and Arazzo to provide deterministic and reliable agentic workflows.

As AI agents become first-class API consumers, a question emerges that linters can’t answer: can an agent actually reason about this API, and use it safely?

Jentic’s AI-Readiness Scorecard addresses the gap between specification validity and machine usability. A syntactically correct OpenAPI document guarantees grammar conformance, not that an agent can interpret intent, construct valid requests, or handle errors gracefully. Developers compensate for ambiguity through trial and error; agents either halt or worse, proceed with confident but incorrect assumptions.

The scorecard evaluates APIs across six dimensions: foundational compliance, developer experience, AI interpretability, agent usability, security, and discoverability. Each dimension produces rich diagnostics that pinpoint exactly where improvements yield the highest gains for both human developers and AI agents. Analysis of 1,500+ APIs revealed consistent obstacles: missing server definitions, authentication buried in prose rather than the spec, sparse or contradictory examples, and broken schema references.

Jentic AI Scorecard Display showing dials in results — Jentic AI-Readiness Scorecard

“AI systems don’t just scan API descriptions; they must interpret, reason, and act on them reliably,” notes Frank Kilcommins, Head of Enterprise Architecture at Jentic and co-author of the Arazzo Specification. “The scorecard provides concrete benchmarks and rich diagnostics on score breakdowns, so you know where you are and what investments will return the most reward. We’re building automatic improvement capabilities leveraging the Overlay specification, helping teams move from insights to actionable fixes.”

You can learn more about the scoring framework, and/or try it for free with your own APIs at https://jentic.com/scorecard.

Finally

Thank you for reading our newsletter. As always, we welcome suggestions on how we can improve it or bring you information that can help make the most of how you use specifications published by OAI. Please get in touch on the Outreach channel on Slack if you would like to work with us to tell your story, to feature in the Ecosystem Spotlight section, or get involved with any of the initiatives described above. We’d really like to hear from organizations, tooling makers, or community members who have success stories to tell, so we can celebrate their successes on the blog.

Until next time!

Contributors: Frank Kilcommins, Henry Andrews, Lorna Mitchell, Ruth Cheesley, Chris Wood.

Dec 04

OpenAPI Initiative Newsletter – December 2025

By Chris Wood Blog

Welcome to the OpenAPI Initiative (OAI) December 2025 newsletter! This is our last newsletter of 2025, and we’ll be reflecting on what the community has accomplished this year as well as looking forward to 2026!

Events News

We’ll start this edition of the newsletter with Events news as our OpenAPI Conference at FOST, the conference formerly known as Apidays, starts December 9! This year the OAI Track has been promoted to a full subconference, with a complete agenda on December 11.

Highlights of the full program at FOST include:

Erik Wilde and Frank Kilcommins wil be running a workshop “API Management for the AI Era: Leveraging OpenAPI Standards” (registration required) which gets to the heart of how you can leverage OAI specifications for AI.
We are hosting an Executive Breakfast where you can learn more about what it means to be an OAI member and meet members of the community. This is an invite-only event, so watch your inbox!
Our subconference starts at 0915 on the Wednesday, and highlights include What’s New in OpenAPI 3.2 (Lorna Mitchell), API Workflow Testing and Mocking with a Single Arazzo Spec (Naresh Jain), and Is OpenAPI still relevant in the age of AI? (Emmanuel Paraskakis).

2026 promises to be an exciting year and in bringing 2025 to close our OAI Ambassador and custodian of the OAI Track Erik Wilde puts the outlook for future events like this: “For the past two years, OAI has actively fostered the OpenAPI community with organizing events at various events, most recently with our first OpenAPI Conference at API Days Paris. We plan on continuing these efforts in 2026, tentatively planning events in San Jose, Singapore, New York, London, Santa Clara, and Paris. If you’re interested in APIs and OpenAPI, join us at one of these events in 2026! We also just launched our very own conference site so that going forward, you can find up-to-date information about all of our events in one place.”

Our new conference and events website has been created to help highlight the work that OAI is doing bringing in-person events to the community, and will provide a complete picture of the agendas, talk and workshop abstracts, and speaker profiles in one place. Massive thanks here to Pavel Kornev, from OAI member SAP, who led the project with a clear vision for a cleaner, more modern experience, with Juri Jatschmenow’s outstanding development work bringing that vision to life. On his teams contributions, Pavel says: “Designing the new OpenAPI Conference Paris 2025 landing page has been an exciting journey for our team. We’re both proud to contribute to the OpenAPI Initiative and thrilled to support an event that brings the community together. This is just the beginning — we’re looking forward to enhancing even more landing pages across the Initiative.”

Initiative News

There’s been a enthusiastic reception to our OpenAPI Specification v3.2 release, with a great deal of coverage and interest from the community in the new features and capabilities. As a reminder, v3.2 provides a host of changes such as the refactored and improved Tag Object, support for the QUERY HTTP Method, support for sequential and streaming data protocols, and additional Security Scheme features like OAuth 2.0 Device Authorization Flow. You can find out more in our blog post), which includes links to key resource to help with upgrading to v3.2. Our Ecosystem Spotlight also provides resources from the community on what the v3.2 upgrade means.

Completing v3.2 means we are now looking at what could appear in our next version and beyond, and the team is ramping up for further releases, with a view to v3.3 that covers improvements to Security Schemes and greater integration with MCP and AI protocols more generally. If you want to find out more, please checkout the Discussions on the OpenAPI Specification repository.

Work has also started for an Arazzo Specification v1.1.0 release, with perhaps the most significant change being the addition of support for AsyncAPI. AsyncAPI support will provide the means to describe workflows for both HTTP-based and message-orientated APIs, providing a significant uplift to how Arazzo can describe sequences of API operations with different architectural styles and provide improved capabilities for calling sub-workflows. Other planned enhancements include improvements to JSONPath and XPath support, and a number of fixes identified since v1.0.1. You can find out more about the plans for v1.1.0 here.

Overlay is also gearing up for a v1.1.0 release, with several features in the frame such as clarifications to format interoperability and a new Parameter Object in the frame. If you want to contribute or simply find out more about what’s going on, head over to the Overlay Specification repository.

Ecosystem Spotlight

We’ve already mentioned the release of v3.2 and we’ve had a great feedback from the community. Here’s a few samples of what folks are saying.

Dave Shanley brought together a really comprehensive overview of all the new features of v3.2 (“I love that new feature smell ”) with plenty of snippets showing exactly how to implement them.
Anton Okolelov also dug deep in his overview, describing streaming support as “a long overdue addition”. He summarizes the value of v3.2 in this way: “While no specification can anticipate every future pattern, OpenAPI 3.2.0 demonstrates a willingness to adapt to observed practices rather than dictating them. That’s a healthy approach for any evolving standard.”
Zaid Daba’een describes the update as focusing “…on the real pain points that show up when you scale: messy docs, patchy auth support, and unclear streaming behavior.”

For the contributors involved in the creation of v3.2, of which there was the greatest number yet in OpenAPI Specification versions, this level of validation is vital for the ongoing development of the OpenAPI Initiative Specifications. Getting great feedback – good and bad – which puts the new features in context are critical to address new features in future versions in earnest, and delivering what the OpenAPI, Arazzo, and Overlay communities really need.

Membership

The work on the Conference website shows the power of the our community, in that a member organization helped bring an exciting new resource to life. We worked hard on revamping our member proposition this year, and next year we are hoping to bring exciting new features to life. If you are interest in becoming a member, head over to the membership page on our website to find out more.

Finally

Please get in touch on the Outreach channel on Slack if you would like to work with us to tell your story, to feature in the Ecosystem Spotlight section, or get involved with any of the initiatives described above. We’d also like to hear from organizations, tooling makers, or community members for further reactions to our v3.2 release, and to share any stories in their adoption journey.

Until next time, and happy holidays!

Contributors: Chris Wood, Erik Wilde, Pavel Kornev, Henry Andrews, Lorna Mitchell

Oct 01

OpenAPI Initiative Newsletter – September 2025

By Chris Wood Blog

Welcome to the OpenAPI Initiative (OAI) September 2025 newsletter! We’ve had a break over the vacation season in the northern hemisphere, but are back to bring you initiative news, information on events and educational resources, and this time round, news of our v3.2 OpenAPI release!

Initiative News

It goes without saying that the big news – wait, enormous – news for this edition of the newsletter is two new releases of the OpenAPI Specification! We have a new minor release at version 3.2.0, which has helped us also deliver a patch version of 3.1 at 3.1.2.

Versions 3.2.0 Features

Version 3.2.0 brings together a feast of new features including:

A brand new Tag Object structure, providing greater flexibility and richness in tagging objects.
Support for the QUERY HTTP method for implementing operations searching collections, plus the new additionalOperations keyword that allows HTTP methods not included in the Specification to be described.
Support for streaming data, which is a critical enhancement to support creating well-described APIs across so many use cases, including chat, AI, IoT, and financial services.
A new querystring keyword that allows all query parameters supported by an API to be described through a Schema Object.
Security Scheme enhancements, including support for OAuth 2.0 Device Authorization Flow and OAuth 2.0 Server Metadata.

You can read more about the enhancement in our blog post, which includes both links to key resources such as the release itself and our comprehensive migration guide published on our Learn site.

Thanks go to the TSC and all contributors for this release, particularly Henry Andrews and Lorna Mitchell for their significant contributions to getting this version over the line!

Moonwalk Update

Back at the start of the year we gave a status update on the progress of Moonwalk: its goals, desired outcomes, and what this Special Interest Group aims to achieve. In that post we said: “The timeline for Moonwalk reaching a 4.0.0 release remains open-ended”, and with the release of v3.2.0 what you are actually seeing is the first incremental step of the larger Moonwalk project. Many of the features of v3.2.0 were ideated through Moonwalk, and our focus is now on delivering more backwards-compatible incremental steps in the 3.x line. We will also keep an eye out for problems that show us that we need to break compatibility and make a 4.0 release, but we would like to discover that need through community feedback.

Key message is: Don’t wait for Moonwalk! Moonwalk is an ideas engine, and feeds the progress on the main development line of the OpenAPI Specification. It may come to pass that there is never a v4.0 of OpenAPI. If you were hanging on for v4.0, make the leap to v3.2 now.

Membership News

We are pleased to welcome new members to the OpenAPI Initiative!

Jentic joined early 2025. Jentic is building the bridge between the AI World and the API World, providing agents with targeted, repeatable, and efficient workflows. Jentic agents are built on OpenAPI and Arazzo, making these specifications crucial building blocks in the Jentic platform. You can read more in our interview with Erik Wilde, who as well as being OAI Ambassador is also Head of Enterprise Strategy at Jentic.

We were also joined in September by Apideck. Apideck is a Unified API provider, with an API that seeks to simplify integration across different SAAS platforms through one integration. Gertjan De Wilde describes their motivation for joining as being “..time to stand behind the spec that has enabled us to build our company.”, which is of course fantastic news, and a great motivation for anyone looking for anyone thinking about becoming a member. We are looking forward to bringing you our new member profile on Apideck very soon!

If you are interested in membership we have held two breakfasts at Apidays (New York and London), where we introduce what membership means and take a look at the revised member benefits we are looking to offer. If you want to find out more, please check out our recent post on LinkedIn, which includes our presentation from this event.

Events News

We have been busy with OAI Track since our last newsletter as event season has picked up again.

API:World was held in Santa Clara in September, where we were lucky enough to host our own OpenAPI Summit. Organized and hosted by Erik Wilde and Frank Kilcommins, the conference kicked off with a workshop held by Erik and Frank that looked at best practices for leveraging OpenAPI and Arazzo when scaling your APIs. This was followed by a full day programme of topics focusing on the MCP (Emmanuel Paraskakis), the role of metadata in building well-connected systems (Simon Heimler), and building great governance for APIs (Jeremy Glassenberg).

Apidays London, whilst not a Summit, still had a host of great talks including an overview of the v3.2.0 release (Lorna Mitchell) and a look at architecting agent-ready infrastructure (Sean Blanchfield).

Last stop for this year will be Apidays Paris, the flagship Apidays event. Please keep an eye out for updates on our agenda for the OAI Track!

Finally, we’ve started issuing digital badges for attendance at OAI events. Our first badges went to participants at our OSS Mini Summit events in Denver and Amsterdam. Be sure to lookout for events and workshops that issue badges in the future!

Ecosystem Spotlight

The Ecosystem Spotlight for this edition comes from Shane O’Connor, Go to Market Lead at OAI member Scalar.

Shane highlights the great work Scalar are doing improving parsing time with their OpenAPI parser:

Scalar has released a modern OpenAPI parser that’s gaining traction for its performance and comprehensive feature set. Written in TypeScript, @scalar/openapi-parser supports OpenAPI 3.1, 3.0 and Swagger 2.0, with support for the newly released OpenAPI 3.2 specification coming very soon. The parser is already trusted by teams at Mintlify & Kong demonstrating its production readiness across diverse use cases, and offering highly significant performance improvements over existing parsers.

Beyond performance, @scalar/openapi-parser offers a comprehensive utility suite including reference dereferencing with tracking callbacks, document filtering, and automatic upgrading from Swagger 2.0 to OpenAPI 3.1 (soon to be 3.2). What distinguishes this parser is its plugin architecture for handling external references. This architecture enables a crucial differentiator: the parser works seamlessly on both server-side and browser environments, unlike many alternatives that are limited to Node.js. Developers can extend it with custom plugins to fetch definitions from databases, CDNs, or any data source. The onDereference callback provides visibility into schema resolution, invaluable for debugging complex multi-file specifications.

As OpenAPI documents grow in complexity and with OpenAPI 3.2 bringing new features, having a performant parser that handles everything from legacy Swagger 2.0 to the latest specification becomes critical for maintaining responsive development workflows. Scalar’s parser represents a modern solution that’s actively evolving alongside the OpenAPI specification itself.

If you’d like to contribute to the Ecosystem Spotlight in our next newsletter, please get in touch on the Outreach channel on Slack.

Finally

Please get in touch on the Outreach channel on Slack if you would like to work with us to tell your story, to feature in the Ecosystem Spotlight section, or get involved with any of the initiatives described above. We’d also like from organizations, tooling makers, or community members on their reaction to our v3.2 release, and to share any stories in their adoption journey.

Until next time!

Contributors: Shane O’Connor, Henry Andrews, Chris Wood.

Oct 22

Announcing OpenAPI Overlay Specification 1.0.0

By OpenAPI Initiative Blog

The OpenAPI Initiative is proud to announce the publication of the OpenAPI Overlay Specification version 1.0.0.

The Overlay Specification is an auxiliary standard to complement the existing OpenAPI specification. An OpenAPI description lays out API operations, data structures, and additional metadata to describe the shape of an API. An Overlay lists a series of repeatable changes to make to a given OpenAPI description, giving a way to apply transformations to OpenAPI descriptions as part of your API workflows.

This specification has been an implementer’s draft for some time, so you may find that your OpenAPI tooling already has or is planning support for Overlays. If you are already using Overlays then you should not see any material changes between an older implementation and the version of the release version. The recent updates aimed to complete the wording and clarify the specification to make it suitable for a formal 1.0 release.

What is an Overlay?

An Overlay is a JSON or YAML file that follows the Overlay Specification and that contains a list of updates applied in the order they appear in the file. Updates might be to add a new value, overwrite an existing value, or remove something from an OpenAPI description.

The following code snippet provides an example of an Overlay encoded in YAML:

overlay: 1.0.0
info:
  title: Fix up API description
  version: 1.0.1
actions:
  - target: $.info
    update:
      title: Public-facing API title
      description: >-
        Description fields allow for longer explanations and support Markdown
        so that you can add links or formatting where it's useful.
  - target: $.paths['/secret'].get
    remove: true

The Overlay itself has high-level metadata in the overlay and info sections that follow the same semantics as an OpenAPI description and will be familiar to existing OpenAPI users. The actions array details each change to make to the OpenAPI, which is applied in order. In the first example above, the first action updates the info.title and info.description fields, while the second action removes the endpoint GET /secret.

A similar example that removes any Path Item that is not labeled to be published to customers, identified using a Specification Extension x-customer-facing, is shown in the following snippet:

overlay: 1.0.0
info:
  title: Fix up API description
  version: 1.0.1
actions:
  - target: "$.paths.*[?(@.x-customer-facing == false)]"
    remove: true

Both examples demonstrate the utility of Overlays, namely to make repeatable, deterministic updates to an OpenAPI description that can be automated throughout the OpenAPI toolchain. The means to apply automated updates is critical to supporting a robust API description pipeline, ensuring that your API community receives accurate and correct OpenAPI descriptions.

Overlay Use Cases

There are several pain points in OpenAPI workflows that an Overlay could be helpful for.

Improve Developer Experience

Your OpenAPI descriptions should be complete and ready for the target audience before publication. You can use an Overlay to add or improve the descriptions and examples that are provided in your OpenAPI descriptions. This is especially valuable where code is generated from a source that does not have a rich set of user-facing content already in place. Overlay provides a standard way to apply upgrades before publishing.

Filter API descriptions

You should remove restricted, deprecated or experimental endpoints before sharing an OpenAPI. If you have a situation where an API operation or even an individual parameter cannot be properly described in the OpenAPI description because the audience is restricted or internal, then an Overlay can be implemented to remove it to provide a “safe” version of the description. You can provide one parent OpenAPI description and use filtering to create reduced versions for multiple audiences as needed.

Translate API reference documentation

If you localize your documentation you can use Overlays to apply translations for the title, summary, and description properties and provide one OpenAPI description per target language. A repeatable translation option can help to keep the processes running quickly and easily. For APIs with global audiences, Overlay is especially valuable as repeatable translation work for APIs can be a tricky problem to solve, and often restricts how quickly your API can iterate.

Add Tool-specific Content

For tools such as OpenAPI gateways, AI consumers, or SDK code generators, additional content in your OpenAPI descriptions can help get the best results. You can use Overlay to add that data at a later stage if you either do not have control over the input OpenAPIs themselves or if you do not want to feed one tool’s metadata to all other tools. You can apply the Overlay to enhance the OpenAPI description immediately before sending it to the tool that needs the transformed version.

There are many more use cases than the ones we have listed. We are looking forward to hearing more about how you use Overlays in your own work.

Extending Overlays

The Overlay specification also includes an extends property so if one Overlay is specific to a single OpenAPI description, this optional field is used to indicate which one. The output of applying an Overlay to an OpenAPI description is … another OpenAPI description – so there are no restrictions on then applying another one!

An example of applying multiple separate Overlays to one API description could be where there’s an Overlay maintained by your technical writers that adds description fields for every operation, and another that makes all the examples of date properties update to a current date, so that all examples are always realistic and useful.

Similarly, one Overlay might be useful for multiple different OpenAPI descriptions, if the same transformation is useful for all.
Examples include applying the same license field to a series of OpenAPI descriptions, or adding an x-internal field on every path starting with /admin.

Next steps

To find out more about Overlay please checkout the following resources:

There’s a list of tools with Overlay support so you can try those out.
More examples from the Overlay Specification are available in its repository.

You can also get involved by following the GitHub repository for the Overlay Specification or join the #overlays channel on the OpenAPI Initiative slack. We look forward to seeing you there!