The OpenAPI Initiative is pleased to announce the appointment of two new co-Chairs of the Outreach Committee. Chris Wood and Pavel Kornev have been nominated to assume the role from Stu Waldron, who stands down after 5 years in the role.We’d like to thank Stu for all his hard work and dedication, and wish him well for the future.
Chris steps up to the role of co-Chair having previously worked on content creation in collaboration with the Outreach Committee and with the community. Chris describes his goals for the role as follows:
I’m delighted to be taking on the role of co-Chair of the OpenAPI Initiative Outreach Committee. I’ve been working with Outreach for a number of years, and am looking forward to taking on a role in which I can help grow engagement across our community. The strength of the OpenAPI Initiative has always been its people, and I want to broaden participation, bring new voices into the conversation, and make it easier than ever for practitioners to get involved with our specifications and the work that surrounds them.
Pavel joins as co-Chair from OAI member SAP, where he has been an active contributor to the Initiative’s outreach efforts, most recently leading the project to design and deliver the new Conferences and Events website.
Pavel shares his thoughts on the appointment:
I’m excited to be taking on the role of a co-Chair of the OpenAPI Initiative Outreach Committee. This is a community I’ve long admired for its impact on how the industry designs and communicates APIs, and I’m eager to help grow its reach even further. I look forward to connecting with contributors, partners, and newcomers alike – and to making OpenAPI more visible, welcoming, and impactful for everyone involved.
Please join us in congratulating Chris and Pavel, and in thanking Stu for his contribution to the OpenAPI community.
We are proud to announce the release of Arazzo Specification v1.1.0!
The headline addition is AsyncAPI support — for the first time, Arazzo workflows can declaratively describe sequences of calls that span both synchronous and asynchronous APIs. A workflow can now call an HTTP endpoint, publish to an event bus, wait for an acknowledgment, and chain the result into the next step — all described in a single, machine-readable document. Beyond that, version 1.1 brings workflow composition improvements, precise data selection, and a set of clarification improvements that address real questions from practitioners who’ve been putting the specification to work. Here’s a quick rundown of the headline features.
AsyncAPI Support
Arazzo 1.0 was built around OpenAPI. Version 1.1 opens the door to event-driven architectures by extending sourceDescriptions to include asyncapi documents alongside openapi and arazzo types:
Async steps reference operations or channels from the referenced AsyncAPI document using operationId or channelPath. Each step declares an action — either send or receive — to make message flow intent explicit:
correlationId links a request to its expected response and must align with the referenced AsyncAPI document. timeout sets the maximum milliseconds to wait before aborting the step.
Steps can also declare explicit ordering via dependsOn — a list of steps that must complete before the current step executes. dependsOn establishes prerequisite relationships; it does not trigger execution of the referenced steps.
Chained Workflow Execution
Action Objects now fully support calling other workflows, with input mapping via the parameters fixed field. This enables clean composition of common patterns — token refresh being the canonical example — across larger workflow sequences:
The new Selector Object enables precise, fine-grained data extraction from structured data using jsonpath, xpath, or jsonpointer. context sets the root node, selector contains the expression, and type indicates the syntax:
The Selector Object is available across workflow outputs, step outputs, request body payloads, parameter values, and payload replacement values.
For cases requiring a specific expression version, the Expression Type Object (renamed from Criterion Expression Type Object) lets you pin both type and version:
type: type: xpath version: xpath-30
Supported values are follows:
jsonpath: rfc9535 and draft-goessner-dispatch-jsonpath-00, defaulting to rfc9535.
xpath: xpath-31, xpath-30, xpath-20, and xpath-10, defaulting xpath-31 .
jsonpointer: rfc6901.
OpenAPI 3.2 Alignment
The Parameter Object gains a querystring option for the in fixed field, treating the entire URL query string as a single value. This aligns with the querystring feature introduced in OpenAPI 3.2 and allows complex query structures to be passed as a single mapped value:
To ensure unambiguous document resolution, Arazzo descriptions can now declare a $self URI at the root level. When referencing an Arazzo description by URI, implementations MUST use the target document’s $self value if present:
arazzo: 1.1.0 $self: https://api.example.com/workflows/pet-purchase.arazzo.yaml info: title: A pet purchasing workflow summary: A workflow for how to purchase a pet through a sequence of API calls description: | Walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.0
This makes cross-document references portable and removes ambiguity in multi-workflow systems.
Clarification Improvements
Version 1.1 also tightens several areas that generated questions in the 1.0 cycle:
Complete ABNF grammar for runtime expressions, with explicit clarity on string embedding
Source Description resolution ordering is now formally defined
Truthy/Falsy evaluation semantics for success criteria conditions are explicitly specified
A Growing Ecosystem
The Arazzo tooling ecosystem has expanded significantly since 1.0. Editors, validators, parsers, resolvers, generators, and standalone workflow execution engines are all available and listed in the Arazzo repository README. This complements the work being done on the openapi.tools website, who have also recently added the ability to list tools supporting the Arazzo Specification.
What’s Next
The roadmap beyond 1.1 includes:
gRPC, GraphQL, SOAP, MCP, and A2A step support
Actor-in-loop (human or agent) support
Transformer and function support
Loops
Get Started
Please checkout the following resources if you are new to Arazzo:
Our thanks to everyone in the community who contributed issues, pull requests, and feedback that shaped this release. Special thanks to Frank Kilcommins, Nick Denny, Kevin Duffey, Naresh Jain, Dmytro Anansky, Vladimir Gorej, and Henry Andrews for their significant contributions and feedback to this version.
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 2024 Talking about 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!
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-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.
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
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 the OpenAPI Initiative.
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.
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
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 the OpenAPI Initiative.
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.
Welcome to the OpenAPI Initiative (OAI) April 2025 newsletter! Our newsletter brings you initiative news, details of new versions of our specifications, and information on events and educational resources.
Initiative News
We’d like to take the opportunity to issue a call to action in our Initiative News section!
We are currently pursuing multiple version lines with v3.2 coming together and Moonwalk deep-diving into the future of the OpenAPI Specification. The project and TSC members especially, are doing a great job in developing the OpenAPI Specification ready for the next challenges an AI-enabled world will bring. We, the OAI, would love to see increased OpenAPI v3.1 adoption! v3.1 brings benefits that will act as a solid foundation for the future development of the OpenAPI Specification, especially with v3.2, and for API providers brings new features and capabilities.
Think of especially important use cases, like presenting conditional objects in open banking or open finance APIs, or providing a true and accurate representation of a JSON Web Token. You’ll quickly find that v3.1 could almost certainly help you. If you are using tooling that you pay for from a software vendor, ask them about their v3.1 upgrade plans today! Please also visit our existing post that provides valuable resources that will help you with your implementation of v3.1.
In other initiative news, Arazzo Specification is currently planning a version 1.0.2 and v1.1.0 later this year. Arazzo adoption continues to grow with tools like Symplr bringing great tools to the ecosystem, and the OAK Repository, which we cover in more detail in our Ecosystem Spotlight section.
Events News
Our conference agenda for the year is well underway! The next appearance of the OAI Track will be at Apidays New York, where Erik Wilde will host insightful sessions on API governance, the role of OpenAPI with generative AI apps, bringing OpenAPI and AsyncAPI together, and a host of other sessions. The Apidays New York strapline is “No AI Without API Management” and will be covering the intersection between AI and APIs. Apidays New York will also feature the Travel Tech API Conference, where OAI Outreach Chair Stu Waldron will feature on an agenda dedicated to travel.
Erik and Frank Kilcommins are also hosting the OAI Track later this year at API:World, the world’s largest and longest-running API and microservices event. APIs leveraging specifications like OpenAPI and Arazzo act as the best canonical knowledge source as we step into the AI-augmented future. If you have an opinion on how these formats can help return on AI investments, then make sure to apply for the track! The call for speakers is still open so if you’d like to join Erik and Frank on stage in Santa Clara please follow the event page link and click on the CFP link.
The event’s roster for 2025 is constantly updated, so please stay in touch with our Events page to see where you can get together with OpenAPI community members for in-person and virtual events.
Ecosystem Spotlight
We are now welcoming highlights from community members who are making a contribution to the ecosystem beyond the core specifications.
The Open Agentic Knowledge (OAK) Repository is one such project. The goal of OAK is to leverage existing OpenAPI and Arazzo description documents to create AI-consumable descriptions that provide intent-orientated workflows. The Repository is now hosting a significant number of descriptions, with over 100 Arazzo descriptions, like the largest collection available at the time of writing.
Thanks to Sean Blanchard for highlighting this work. Sean describes OAK as follows: “MCP might be someone’s preferred transport, but OpenAPI/Arazzo should be the schema. We are particularly excited about converting the whole repository to OpenAPI 4.0.” Identifying and evolving key intersections, such as OAK, for the growth of AI-powered ecosystems is vital for leveraging all the important work that has gone into bringing the OpenAPI and Arazzo specifications to life. Moreover, as Frank Kilcommins describes it “Open standards like OAK ensure interoperability and reduce fragmentation”.
We excitedly await the future development of OAK.
If you’d like your project covered in a future newsletter please let us know by getting in touch on Slack.
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 the OpenAPI Initiative. 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.
It time for our next Community Hero, and this time we talk to Leviathan of the API world Phil Sturgeon.
Phil is author of Build APIs You Won’t Hate, ex-WeWork system architect, ex-Stoplight product manager, and now working on Green Tech and API consulting.
Phil gave us some insights into the early days of OpenAPI, what he thinks would be great in version 4.0, and his hopes for a future of green software.
What drives your interest and involvement in the OpenAPI Specification?
The first time I tried to document an API I thought “this is a bit of a mess”, and for years it always was. It involved so much repetition, restating exactly the same interface already written down in integration tests, contract tests, serializers, validation logic, serializers… all in mismatching formats that needed awkward conversions at various phases of the API lifecycle.
OpenAPI appeared as the solution. It took a little work to get JSON Schema and OpenAPI v3.1 lined up properly, and various other corners needed rounding off, but getting involved with the OpenAPI spec and helping to define the OpenAPI-based API Design-first workflow has made life easier for API designers and developers all the way through the API lifecycle.
What do you consider to be your most significant personal contribution to the development of OpenAPI?
API linting and automated style guides have been a passion ever since working as a systems architect helping 100+ developers on various teams get started with OpenAPI. There was barely any tooling around for this concept and there were countless mistakes being made often, so I created Speccy to guide teams in how to avoid these mistakes in their OpenAPI and the actual API being designed.
This later inspired Spectral, and I joined the Stoplight team to help. As product & project manager of the open-source tool, and with a brilliant team, we created something so powerful that every major OpenAPI tooling vendor has integrated Spectral into their own tooling. It’s helping countless API teams around the world from tiny startups to massive corporations.
Automated style guides are now a regular part of making APIs consistent, useful, and even secure. For those working on API governance, it’s removed the most horribly boring and confrontational parts of API design reviews so that robots can handle all that rubbish.
Working on something as big as Spectral has been an amazing experience, even now as alternatives are gaining popularity, they are replicating its functionality and maintaining compatibility with the Spectral ruleset format. I love talking to these teams to help them avoid mistakes I made, share ideas we never got around to doing, and generally develop a better API linter so that the space can keep on evolving for years to come.
What do you see as the most exciting proposed features of version 4 of OpenAPI?
There’s a lot to be excited about, and a general tidy up and reduction in nested structures is going to help a lot of people not lose feeling in their fingers. For me the most exciting part is the increased use of standards.
Using JSON Schema to describe parameters via parameterSchema instead of a OAI Parameters Object will reduce complexity for tooling developers trying to figure out the complexities of style, explode, etc., something that is almost impossible to get right even if you dedicate your life to it.
Then of course there’s OpenAPI using proper URI Templates instead of something that looks a bit like URI Templates. Once again this makes life easier for tooling developers, but more importantly it will mean more powerful tooling coming quicker as these components can be plopped together like Lego bricks. This all means more options for end users and a better healthier ecosystem in general.
The OpenAPI Initiative is now a multi-specification organisation. How will the project change now that we deliver more specifications to the API community?
The extended Marvel Universe of OpenAPI specifications is getting really interesting, and it’s fantastic to see tooling vendors jump on board to integrate them into their offerings. This creates far more extension points and opens up far more interesting workflows for OpenAPI-based tooling.
For example, Overlays were initially thought to be mostly helpful to technical writers, but have finally solved the problem of getting generated SDK examples from one provider embedded in API reference docs using completely different tools. This allows tooling vendors and end users to keep working on imaginative integrations in a standardized way so nobody has to waste their time on “SpecOps” a.k.a building weird brittle CLI scripts that mush YAML about.
Arazzo has defined the one workflow format for testing tools instead of everything building their own, but it’s also being used by OpenAPI-based documentation tools to break free of being API reference documentation only, documenting complex workflows without loads of copying and pasting into Markdown documents.
I am curious to see what else the Special Interest Groups can get over the line, and excited to see what that does to the wider API ecosystem.
What do you see in the future for the OpenAPI Specification?
An increase in API design-first workflow now that the tooling has matured in all ecosystems enough for it to be quicker than not doing it.
At the same time I see a lot of improvements in OpenAPI-aware frameworks, and I’m excited to see more of that. Instead of writing a bunch of code then slapping some attributes around in the hope that they’re correct, these frameworks consider OpenAPI at its core, meaning that merely building the framework is generating OpenAPI.
If done properly I’m hopeful we’ll see a true hybrid approach, where people build things entirely API Design-first, then generate code in these OpenAPI-aware frameworks, and are able to accurately evolve it from there, getting the perks of both works without any of the downsides.
What other standards developments do you consider particularly significant for the API economy?
Currently 2% of global CO2 emissions come from the internet and associated devices, and 80% of web traffic is APIs. I think we’re in an incredible place to have a meaningful impact on global emissions by simply learning to track emissions of our APIs and reduce them through some of the Green Software Foundation’s projects. If every single API developer reading this took the free Green Software Practitioner course and invited a few colleagues to do the same, we’d be off to a great start.
Should more people get involved in developing the OpenAPI Initiative specifications and why?
Absolutely! Literally anyone can join the calls, and for a conversation about improving a YAML/JSON-based machine readable API description format they were honestly really fun.
Sometimes there are quite a few people, but sometimes there’s just the same handful. Whether you are bringing experience or fresh eyes, it’s all good stuff, and even if you just mostly listen to a few you might find you are learning, and you might find yourself sharing and contributing more than expected.
The OpenAPI Initiative has a new member! We are pleased to welcome GitBook to the OpenAPI family. GitBook provides tools for building great documentation that developers love, and leverages the OpenAPI Specification in the documentation pipeline. OpenAPI descriptions can be automatically imported by GitBook to provide the backbone of published documentation.
We talked with Addison Schultz, Developer Relations Lead and GitBook representative at the OpenAPI Initiative.
Please tell us about your organization and your needs in publishing well-described APIs.
GitBook is a modern documentation platform that helps teams create clear, well-structured public documentation, including API references. As an API documentation platform, our priority is to ensure that teams can easily create high-quality, up-to-date, and beautiful documentation. Teams need a solution that allows them to present API details in a structured way, automate updates as APIs evolve, and offer an interactive experience for developers to explore endpoints. Clear, accessible API documentation improves developer adoption, reduces support requests, and enhances the overall API experience – and that’s where GitBook fits in perfectly.
The OpenAPI tooling world is vast, with many approaches to leveraging OpenAPI to provide a great developer experience. How do you make the most of the features of OpenAPI in delivering your tool?
I think that any improvement to the spec that lets developers standardize their workflows is a win. When you have a more consistent way of documenting work, it not only makes life easier but also reinforces the value of good API documentation. The first point of a product for many teams is visiting APIs through a company’s documentation – and any way that we can provide to make that easier, more effective, and engaging is what I think will provide the biggest impact for getting more users to understand and work successfully with your product or API.
We’re currently building a report on the future of API documentation as well – and would love all the input we can get! You can find our the survey here.
What is the most important factor in your decision to become an OpenAPI Initiative member?
We have big plans for improving the ways developers document products and APIs – and because OpenAPI leads the way in crafting the way the world creates APIs, we want to be close with the teams who are pushing the spec forward and to make sure we can work together on pushing documentation in the same direction.
How would you like to see the OpenAPI Specification evolve in the future?
Any way the specification improves that allows developers to standardize their workflows even more is a great improvement in general, as it will allow them to also document their work in more standardized ways. We also want to help promote the overall importance of teams to document their APIs, and show the impact it has.
What role do the OpenAPI Initiative specifications play in the evolution of APIs and AI?
Similar to the question above, the more teams are able to standardize their work, the better they’ll be able to create more cohesive products and experiences – including products with AI. The OpenAPI specification is a great example of what teams can use to build better products overall.
Any final thoughts that provide insights on how you use OpenAPI that you feel is of interest to the community?
At GitBook, OpenAPI plays a key role in helping us and our users create dynamic, always up-to-date API documentation. By leveraging OpenAPI definitions, we enable users to create seamless synchronization between their API specs and documentation, reducing a lot of the manual effort needed to ensure accuracy. This improves the developer experience a lot, and as APIs continue to evolve, we see OpenAPI as an essential standard for driving clarity, automation, and accessibility in API documentation.
Thank you Addison for taking the time to talk with us!
Joining the OpenAPI Initiative
Want to become a member of the OpenAPI Initiative? Find more information here.
While you think about it, please checkout these resources:
The OpenAPI Initiative 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.
The OpenAPI Initiative has grown to a multi-specification that, first and foremost, provides the OpenAPI Specification, the most popular API description language available to API providers and consumers. The OpenAPI Initiative also supports the development of the Arazzo Specification, which caters for complex workflows invoking many APIs, and the Overlay Specification which provides the means to deterministically and reliably update an OpenAPI description through automation.
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.
Welcome to the OpenAPI Initiative (OAI) February 2025 newsletter, the first of this year! Our newsletter brings you initiative news, details of new versions of our specifications, and information on events and educational resources.
Initiative News
2025 got off to a great start with the release of version 1.0.1 of Arazzo. If you don’t know about Arazzo, it’s a specification designed to describe complex, multi-step workflows that invoke multiple API operations and is aimed at simplifying integrations in our multi-cloud, multi-platform world. Version 1.0.1 is aimed at providing important clarifications without altering core functionality, ensuring greater clarity, improved examples for implementers, and corrections of minor inaccuracies. You can read more about the release, including the proposed 2025 release schedule for Arazzo in our blog.
Work continues on version 3.2 of the OpenAPI Specification, with several changes already accepted in the work-in-progress version. Features include:
Security changes including support for Device Authorization Flow, a new property to signpost OAuth 2.0 Server Metadata and deprecated OAuth2 schemes.
A new Tag Object format, with the ability to categorize and nest your tags to create an expressive, hierarchical structure.
Version 4, codename Moonwalk, will also continue to evolve in 2025. Insights from Moonwalk have helped to evolve the 3.x release line, as they were backwards compatible, with the version 3.2 features mentioned above. Please read our latest post on Moonwalk for more information on where the work is going.
One final note is that our OpenAPI specification page now supports dark mode! We are dedicated to ensuring usability for our specifications, so this is an important feature to add to our specification website. Please head over there to check it out.
Events News
2025 also saw the early appearance of the OAI Track at DeveloperWeek 2025, an industry-leading developer event that hosted the OAI Summit. The Summit provided two workshops on OpenAPI, hosted by Erik Wilde and Frank Kilcommins followed by 11 sessions covering topics including Arazzo, Overlays, API Governance, and the intersection between APIs and AI. Our thanks go to all who participated in the Summit and helped bring many aspects of the OpenAPI Initiative world to life for conference attendees.
The end of February also saw Leap 2.0, held by OpenAPI member Tyk. Leap 2.0 is a virtual conference hosted by BGB chairperson Budha Bhattacharya. The conference is focused on all things API governance and includes presentations from current OpenAPI TSC member Lorna Mitchell and OAI luminaries including Kin Lane. API governance in the world of API sprawl and AI growth, especially with the advancements in Retrieval-Augmented Generation (RAG), means that having a strong grasp on both API design and deployment is vital for API providers.
The event’s roster for 2025 is constantly updated, so please stay in touch with our Events page to see where you can get together with OpenAPI community members for in-person and virtual events.
Outreach Initiatives
The Outreach committee focuses on community engagement and marketing for OAI. We have some goals we’d like to achieve in 2025, and the newsletter provides a great opportunity to publicize these.
First off, we are looking to expand our blog to include success stories from the OpenAPI community. Have you used OpenAPI, Arazzo, or Overlay in a way that has changed or even revolutionized your working practices? Have you delivered solutions that have delighted your customers, or your internal stakeholders, using an OAI Specification as the foundation? You may use the OpenAPI specification indirectly, as it is abstracted by the tooling you use, but we’d still like to hear about your experiences.
We are also looking to expand our training and certification offering to help provide clear and consistent education on OAI specifications in the community. We are currently in the ideation phase, looking at how to provide a certification mechanism for training that delivers knowledge of the OAI specifications, as a means for anyone using OpenAPI, Arazzo, and Overlay to attest their knowledge. If you are a training provider and interested in collaborating with OAI on providing certified training we’d love to hear from you.
Lastly, we are introducing a new feature on our LinkedIn page called #happyfriday, where we post articles brought to us from the community. If you’d like to contribute to this, please follow the instructions below to get in touch.
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 the OpenAPI Initiative. Please get in touch on the Outreach channel on Slack if you would like to work with us to tell your story, or get involved with any of the initiatives described above.
Welcome to the next installment of our series of posts on people we consider to be heroes of the OpenAPI community. These people go above and beyond to contribute to the OpenAPI Initiative specifications, Special Interest Groups (SIG), or across the OpenAPI Initiative (OAI).
Our next Community Hero is Erik Wilde. Erik is an API industry expert and OAI Ambassador, and is responsible for the OAI tracks that have been a feature of the API events landscape in 2023 and 2024, with more to come in 2025. Erik has a background in research and academia, having held the roles of Associate Adjunct Professor and Assistant Professor at Berkley. He has contributed to many publications, patents, and standards, and worked with various industries and sectors, such as healthcare, education, finance, and government.
Erik filled us in on why he is involved in the OAI and his views on the role of standards in the industry.
What drives your interest and involvement in the OpenAPI Specification?
OpenAPI is one of the fundamental building blocks of today’s digital economy. It’s just a minor exaggeration to say that 100% of organizations today depend on OpenAPI in some place of their IT landscape to be able to do what they do.
Standards sometimes get a bad reputation as constraining things too much. And of course they do constrain things and there also are standards out there which possibly could have been designed better. But the important aspect is that standards create real value and they do so because people agree that using them is better than not using them.
OpenAPI has become the dominant standard for API descriptions and is effectively powering today’s global digital landscape. It’s thrilling to be part of that movement, and it is rewarding to try to help with improving the standard itself and improving the way how people learn about the standard and how to use it. We have ambitious goals for the OpenAPI Initiative to increase our visibility and make it easier for people to learn and adopt OpenAPI. I am optimistic that 2025 will change a fair bit how OAI is operating and how we engage with and help the global API community.
What do you consider to be your most significant personal contribution to the development of OpenAPI?
Right now it is probably the visibility and community around OpenAPI. I have been organizing OAI Tracks at various conferences for almost two years now. It’s always rewarding and interesting to see the many different contributions and ways how organizations are using OpenAPI.
OAI has an excellent technical arm that makes sure that OpenAPI remains a technically sound and well-designed specification. What we currently lack is a better connection with our community of OpenAPI users.
On the one hand we need that to make sure that more people are learning what OpenAPI is and how to use it. We also want more people to read our case studies and reports (planned for 2025!) so that they better understand what it takes to use OpenAPI well.
But on the other hand we also need more and better feedback from the community. What are the features people find most useful? What are features that seem to introduce complications? What are features that are missing? And what does the tool landscape out there actually implement, which brings us to the surprisingly difficult question to decide what “implementing OpenAPI” really means (which is a fascinating topic in itself and another major 2025 activity for OAI).
I think we need a larger base and better visibility in the community as a necessary step to better plan how to evolve the specification in a way that’s most useful for its users.
The OpenAPI Initiative is now a multi-specification organisation. How will the project change now that we are delivering more specifications to the API community?
Quite a bit of that is terminology and branding. We have a rather unfortunate name now that we’re not just managing the OpenAPI specification. We’ll be able to work with it, but we need to reassess our branding and things like our information architecture in general.
Our website is currently undergoing a major analysis and redesign and hopefully we will end this year with a prettier, easier navigable, and easier manageable website. One part of it is just improving things that we’ve known for a while, but taking the multi-specification aspect into account is one of the major reasons for the redesign.
What’s great is that our two new specifications are fitting into rather specific and easily explainable gaps. This means that our story of how we support the API landscape becomes more complete and overall a more convincing story. It also means that we can tell better stories of how tools and tool chains can be used because there are interoperable descriptions of various aspects throughout the API lifecycle.
In the end, being a multi-specification organization has increased the potential of OAI as a unique provider of solutions in the API space. But it also has made it a bit more challenging for us to tell our story and the story of our specifications. What do you see in the future for the OpenAPI Specification?
One of the important tasks going forward is to better understand if and how could be improved to better support AI scenarios. It might be as simple as adding some guidance around API design and how to best write the OpenAPI description for AI consumers. This is particularly interesting for AI agents which probably would want to discover higher-level information on how to use an API, for example in an Arazzo workflow description.
But we may also see that AI scenarios are requiring updates to OpenAPI, to other OAI specifications, or maybe will need entirely new specifications. We’re only at the beginning of understanding the potential and impact of AI scenarios, but I am sure that a year from now we will have a better idea about how to make OpenAPI more AI-friendly.
Personally, I think the current version has proven to provide enough value for us to invest more into explaining that value and making it easier to realize. It’s not OAI’s goal to turn into an API consulting firm, but given our unique position in the API landscape we can provide trainings, case studies, and reports with more authority than most other entities out there, and it would help our users if we did more of that.
What other standards developments do you consider particularly significant for the API economy?
First and foremost our “sister specifications” that are also part of the Linux Foundation have to be mentioned: AsyncAPI and GraphQL. And then there’s of course gRPC which is not part of the Linux Foundation but still can be considered an open standard. So these are the big ones complementing OpenAPI when it comes to providing open and established technologies for various API styles.
When it comes to OpenAPI itself then of course we have standards like JSON Schema, OpenID, and OpenID Connect (OIC), which are very central to using OpenAPI APIs and need to be treated as an almost integral part of OpenAPI by now.
What we may also see is some variant of a catalog format, where it is possible to advertise API catalogs and to describe APIs in those catalogs with machine-readable API descriptions and other metadata that may be helpful to work with the API. Since we do see more and more scenarios where scaling the API practices is one of the challenges, we may see such a catalog format emerging as a way to more easily share APIs.
Should more people get involved in developing the OpenAPI Initiative specifications and why?
Yes, it would be great to see more people getting involved with OAI. We want to play our part by creating more useful content going forward, in particular in terms of training, case studies, and reports. These things will help OpenAPI users, but the more we can create these based on feedback, the more likely we will create the ones that have the most impact.
In my mind, APIs still are too often treated as a mere side-effect of having an IT landscape where components need to be connected. Of course we need APIs on this very basic level, but in many organizations there is a lot of unrealized potential because APIs are not managed strategically. We still need to be better at telling the story of API representing business capabilities, the option value that they bring to an organization, and the steps it takes to create the right APIs and to create them the right way.
We’re only getting started with Getting APIs to Work at OAI, and given that we have big plans for 2025 this is the ideal time to join the movement, start engaging with OAI, and help us to better understand how we can better help you and the API community in general!
