Blog – OpenAPI Initiative

Jun 09

OpenAPI Initiative Newsletter – June 2026

By Chris Wood Blog

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

We are excited to bring all the latest specification, events, and community news across the OpenAPI, Arazzo, and Overlay specifications and the wider community.

OpenAPI Specification

The OpenAPI Specification (OAS) team is evaluating changes for v3.3, with a number of items in scope.

Firstly, the team is investigating a concept that we’re calling “Standardized API Features”, or SAFs. As the name suggests SAFs are intended to provide a mechanism for characterizing features of OAS according to two properties, namely: the feature has standardized behavior defined by an external specification (such as an RFC), and it requires an exception to the normal rules for describing API operations in OAS. Cookies are the clearest example: their behavior is defined by RFC 6265, and they need special treatment in OAS because the Cookie header cannot simply be described using the standard header parameter approach.

The SAF concept is therefore intended to help the specification community learn from past design mistakes and reason more clearly about which API features deserve first-class, dedicated treatment in the Specification versus those that can be described generically. The SAF concept therefore provides significant affordances for the development of new features in both v3.3 and all future versions.

Alongside and supported by the work on SAFs v3.3 promises to be one focused on API Security, with investigations already taking place on supporting the FAPI 2.0 Security Profile and Grant Negotiation and Authorization Protocol (GNAP) available. Discussions have already started on what a Security Profile might look like, and the work on SAF will help shape how this is introduced.

Arazzo Specification

The Arazzo Specification v1.1.0 has also been released. This is a minor release built on the 1.0 foundation, with the headline addition being AsyncAPI support. For the first time, a single Arazzo document can describe workflows that span both synchronous HTTP operations and event-driven asynchronous APIs.

Other significant additions include fully supported chained workflow execution (enabling reusable sub-workflows such as token refresh flows), a new Selector Object for fine-grained data extraction via JSONPath, XPath, or JSON Pointer, and alignment with OpenAPI 3.2’s querystring option on the Parameter Object. The release also tightens specification precision with a complete ABNF grammar for runtime expressions, formally defined truthy/falsy evaluation semantics, and a new $self field providing a canonical URI for unambiguous multi-document referencing.

Existing 1.0.x documents remain valid without structural changes, and the roadmap ahead targets gRPC, GraphQL, SOAP, MCP, and A2A step types, actor-in-loop support, transformer/function support, and loops.

Overlay Specification

2026 has already seen the release of Overlay v1.1.0, which we covered in our February newsletter. A release v1.2.0 is currently in the works, which will implement Reusable Actions.

Reusable Actions are important because they vastly increase the means for creating Overlay actions that can be used in multiple places, both within and across documents. As a framework for implementing automated pipelines this feature is key, as it ensures that Overlay documents provide the full corpus of knowledge for the pipeline.

The release date and final scope for v1.2.0 is yet to be fixed, but we’ll keep you up to date with news on the release.

Getting Involved

We want to acknowledge the efforts of our specification team members and community in bringing these releases together. Many hours are spent in ideation, drafting, and review, and the specifications are always on the lookout for help.

The work on Security Profiles also shows how the involvement of experts across the industry is tremendously important, and discussions between OAI more widely and the FAPI Working Group have taken place. This level of community engagement across different standards bodies is vital in helping OAS, Arazzo, and Overlay evolve and develop to meet the needs of the ecosystem, especially in supporting Agents and AI more generally with features that support automation and autonomy.

If you want to get involved – either by helping with the authoring, or bringing fresh ideas or expertise to the community – you can come and join the specification meetings for OpenAPI, Arazzo, and Overlay on our Community Calendar. If you can’t make the meetings you can also get keep in touch, ask questions, or suggest ideas on Slack, using the #spec, #arazzo, and #overlays channels.

Finally, each specification is open to discussions on Github, so you can also raise ideas or contribute there. See the OpenAPI, Arazzo, and Overlay repository discussions for more details.

Events News

The OAI Track – led by Erik Wilde – has continued to bring exciting and insightful sessions to conferences around the world, with DeveloperWeek San Jose, and Apidays Singapore and New York already complete.

The agenda of these events was dominated by the intersection of OpenAPI and artificial intelligence, with a consistent focus on what it means for an API to be truly “AI-ready.” Speakers like Emmanuel Paraskakis and Kin Lane repeatedly returned to the idea that OpenAPI documents must evolve beyond human-readable documentation to become machine-actionable contracts that AI agents can discover, reason over, and execute reliably. A second strong thread was the shift toward spec-first and API-first development practices, framing the OpenAPI description as the single source of truth that drives design, code generation, testing, and governance.

Ashish Khichi at Apidays Singapore 2026 Talking about Spec-Driven Development

Workflow orchestration has also emerged as a distinct concern, with multiple sessions led by Frank Kilcommins exploring how standards like Arazzo and MCP can extend OpenAPI into the multi-step, agent-driven interactions that modern AI systems require. Underpinning all of this was a practical emphasis on tooling and automation and moving from from AI-assisted API design and automated linting to SDK generation and contract testing, reflecting an industry moving from manual API development toward highly automated, standards-driven pipelines.

The busy conference season continues, with Apidays Amsterdam and Apidays Munich in June and July respectively. We’ll be continuing with the themes above, so if you are interested in hearing more about the intersection between OpenAPI and AI, be sure to make it to the OAI Tracks!

Ecosystem Spotlight – Interledger Foundation and Open Payments API

The Interledger Foundation SDK Grant program is funding work to improve the developer experience for the Open Payments API, which is an open standard for payment interoperability across different providers, rails, and ecosystems. The SDK Grant program is specifically interested in making GNAP available in the OpenAPI Specification as a key affordance to their developer experience goal.

Interledger SDK Grant banner showing OpenAPI and Arazzo logos

The Interledger Foundation has therefore funded three proposals that advance both the OpenAPI and Arazzo Specifications while improving the developer experience for the Open Payments API.

The grantees are:

Henry Andrews is leading work to add GNAP as a Security Scheme to the OpenAPI Specification, addressing a gap in security description capabilities that matters increasingly for code generation and AI agents.
Chris Wood is supporting the GNAP implementation, producing a TypeScript version for Microsoft’s open-source Kiota SDK generator, and updating OAI educational materials to reflect the new support.
Vincent Biret is implementing Arazzo workflow support in Kiota for C#/.NET as a reference implementation, enabling client code to generate higher-level API workflow SDKs directly from Arazzo documents.

These three work streams demonstrate how OAI specifications underpin real-world tooling investment and deliver benefits across the broader web API ecosystem.

Outreach

Telling and promoting success stories from the community is a big part of what outreach at OAI aims to achieve. We’d like to hear from you 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 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.

We are also actively investigating new ways of engaging with the community and especially with OAI members, with office hours and tooling forums to address the needs of the community more readily.

You can in touch by:

Using the #outreach channel on Slack.
Emailing us at outreach@openapis.org.
Getting in touch at our LinkedIn page.

If you have something to share, be sure 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 OAI.

Until next time!

Contributors: Chris Wood, Karen Etheridge, Henry Andrews

May 19

Announcing Arazzo Specification 1.1

By Chris Wood Blog

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:

sourceDescriptions:
  – name: PaymentsEventBus
    url: ./user-payment-events.asyncapi.yaml
    type: asyncapi

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:

– stepId: WaitForUserAck
  operationId: $sourceDescriptions.AsyncAPIEventBus.receiveUserAck
  action: receive
  correlationId: $steps.GetUser.outputs.userCorrelationId
  timeout: 10000
  successCriteria:
    – condition: $message.payload.status == "ok"

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:

name: retryStep
type: retry
retryAfter: 1
retryLimit: 3
workflowId: refreshTokenFlow
parameters:
  – name: refreshToken
    value: $inputs.refreshToken
  – name: clientId
    value: $inputs.clientId
criteria:
  – condition: $statusCode == 401
  – context: $response.header.WWW-Authenticate
    condition: '^.*[,\s]error="invalid_token".*$'
    type: regex

Advanced Selector Support

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:

outputs:
  userEmail:
    context: $response.body
    selector: $.user.profile.email
    type: jsonpath

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:

– name: searchParams
in: querystring
value: "filter=active&sort=desc&limit=50"

– name: fullQuery
in: querystring
value: "category={$inputs.category}&minPrice={$inputs.minPrice}&inStock=true"

Identity-based Referencing

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.

Contributors: Frank Kilcommins

Mar 05

OpenAPI Community Hero – Vincent Biret

By Chris Wood Blog

Welcome to our next Community Hero! After his recent efforts in contributing to Overlay v1.1.0, we spoke to Vincent Biret.

Vincent is a Principal Software Developer at Microsoft AI Foundry, and previously worked on Microsoft Graph. He is a long time open source contributor, international public speaker, and is passionate about developer experience.

Vincent gave us his thoughts on the Overlay, the Open Initiative specifications in general, and why being involved in contributing to the specifications is so valuable.

What drives your interest and involvement in the OpenAPI Specification?

Participation in the OpenAPI initiative is a growing opportunity. It also enables so much of the work I do at Microsoft. And I’m a long believer of the “contribute back to the things you’re using” model.

About 5 years ago, I started to work on a client code generator, Kiota, which meant I needed to learn a lot about the OpenAPI Specification. The TDC felt like a “natural place” for me to learn was to sit (at first quietly). This call felt welcoming and taught me a lot about “how standards work, and who are the people behind it”. I gradually felt comfortable contributing back.

Thanks to the help of many others, some of them featured in this blog series, I’ve been able to make meaningful contributions to OpenAPI 3.2.0, and lately to Overlays as well.

The OpenAPI Initiative is now a multi-specification organisation. How do you see the project changing now that we deliver more specifications to the API community?

Before getting involved in the OpenAPI initiative, I didn’t suspect how much work and coordination goes into standards authoring. The bigger the standard, the more work required to put together a new version. And that growth is not linear.

The size of the standard also impacts the “consumer” side, implementers need to keep more context in mind, users require more effort to discover any given feature, etc…

There is a general recognition among the regular contributors that we can move faster with a set of “dedicated and interconnected specifications” rather than a monolithic one. This structure unlocks additional value for consumers through better focus and clarity, faster releases with more features, easiness to implement, etc…

A clear demonstration of this approach works:

About 2 years ago, the main repository had about 1000 open issues, this was not manageable. Now we’re at about 100. Thanks to the hard work of Lorna, Henry and others, some of those issues were “grouped by problem areas” into Arazzo or Overlays. Those issues were then handled by dedicated teams. This approach facilitated the 3.2.0 release of the core specification through better focus on the core concerns.

You recently contributed to v1.1.0 of Overlay. What was your motivation for implementing the new features you provided to the community

I now work on Microsoft AI Foundry, which provides a superset of the REST API provided by OpenAI. To enable those experiences, we use TypeSpec as a design language and as a support for a lot of our tooling.

In that context, we need TypeSpec definitions for the OpenAI surface of the API but we don’t want to handcraft them. After all, we’re talking about approximately 300 operations, hundreds of models, all of which change weekly.

In our import process, we use Overlays to massage the OpenAPI description OpenAI provides into something that better fits our needs. At some point we found ourselves maintaining a lot of “update actions” that contained duplicated sections from the source description. Those duplicated sections quickly became stale and unmanageable.

After scanning through the Overlays repository, I quickly noticed this was a common limitation others were sharing. So not only to enable a better workflow for my team, but also to give back to the community, I thought I’d propose a solution to that problem. And thanks to the help of many others, like Ralf Handl and Mike Kistler, we finalized the feature!

This feature, and additional contributions from many others eventually became version 1.1.0 for everyone to enjoy.

The Moonwalk SIG continues to look to the future of OpenAPI, and investigate new features that could be of value to our specifications. What are you most excited about as a future feature of any of the specifications?

Although I’m not involved in the Moonwalk SIG (there are only so many hours in a day), we have a great model here: Moonwalk is the “think tank” for large, fundamental and long-term concerns that are not addressed today in the specification. Where possible, some of that thinking gets ported in a 3.X version.

This approach has many benefits:

The community gets value sooner than waiting for a big-bang release for years.
The specification authors get feedback on any solution, leading to a more mature iteration in the “big release”.

Beyond this process that feeds features into the minor releases, I’m excited about a few foundational breaking changes that are needed to enable additional scenarios:

The notion of “parameters groups/sets”: today you can’t really express “if you provide query parameters X/Y/Z, you’ll get response alpha, but if you provide A/B/C, you’ll get beta”. (especially useful when the API provides the ability to select fields from the response).
Better integration with RFC6570 URI template. This will simplify the specification a great deal, and enable a more structured approach to code generation, etc… This will also solve once and for all ambiguities around whether paths might be conflicting or not based on their path parameters/constants.
Maybe new things around how authentication and authorization can be discovered by agents/code-generators to enable better automation? This has been an historical gap of the specification.
Maybe support for additional protocols? (we’re started some work with webhooks, and in 3.2.0 streaming)
Maybe better lifecycle information? (read and write only are “left to interpretation” today)

(this is just my wishlist, I don’t actually know whether the SIG is working on any of those things)

What do you see in the future for the OpenAPI Specification?

Keep in mind that I’ve only been involved (as in more than just using) in the specification about 3 or 4 years ago, so I might not have sufficient perspective here to provide an accurate answer.

But from my perspective, it seems to me the OpenAPI Specification is both charting the course in the API space, and also closely listening to where the broader IT industry is going.

Right now, the industry has a HUGE focus on the LLM/AI/agentic space. And OpenAPI fits well in that space because it’s text based, broadly adopted, mechanically parsable, etc… So I think we’re going to see that at least some of the investments will cater to that problem space.

Longer term, I think I can see two challenges arise:

This is a lot of work done by people. We need to ensure this work remains sustainable by supporting the people working (funding etc…). Especially contributors who are not on the payroll of big corporations like I’m fortunate to be. All the great additional features in newer versions are only beneficial if end users are aware of them, and if tooling supports it. We probably have a lot of work on the advocacy side.

What other standards developments do you consider particularly significant for the API economy?

I’d like to acknowledge we rest (pun intended) on the shoulders of giants: HTTP, TLS, TCP/IP, DNS,etc… All of that is infrastructure, and like any infrastructure it requires ongoing investments to operate safely and at peak efficiency.

Additionally, we’re seeing co-benefits from adopting existing standards as much as possible in the API space: JSON Schema, RFC 6570 Uri template, RFC 9535 JSONPath query expressions for JSON, and many more. Re-using existing standards allows us to focus on the additional value we can provide, while unlocking efficiencies from integrating with existing eco-systems.

I’m also keeping an eye on emerging standards from the AI space: MCP, A2A, UTCP…

Why should more people like yourself get involved in developing the OpenAPI Initiative specifications?

It’s a tremendous learning opportunity, the community is super nice, there’s work to do, and giving back (your time, money, etc…) is generally speaking a nice thing to do. It can seem like a scary new space, but with time and dedication you’ll get used to it.

I also especially encourage people who are not like me to join, because having too many “individuals like me” would be a disaster 😉.

Author: Vincent Biret

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 2025 — 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!

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 16

The OpenAPI Initiative Welcomes Apideck!

By Chris Wood Blog

The OpenAPI Initiative (OAI) is proud to welcome Apideck as a new member!

Apideck is the first Unified API platform to join OAI, and their membership is reflection of their huge commitment to open source. Alongside joining OAI, Apideck also created and maintains Portman, an open-source library that streamlines API contract testing using OpenAPI definitions.

We caught up with Gertjan De Wilde, Co-founder and CEO of Apideck, to find out more about their motivation for supporting OAI, where OpenAPI, Arazzo, and Overlay fit in their product and architecture, and their outlook for the future as an OAI member.

Please tell us a bit about your organization and your needs as an API provider in publishing well-described APIs.

Apideck is a Unified API platform that provides 200+ integrations across multiple categories, including Accounting, HRIS, CRM, and others. We normalize disparate APIs into consistent, predictable interfaces. As the first unified API company to join OAI, we have unique needs: we must maintain consistency across hundreds of different API providers. Well-described APIs using OpenAPI specifications are essential for us to document complex integrations in a standardized way and provide predictable interfaces that developers can trust. Our entire business model hinges on transforming diverse API implementations into a unified, coherent interface with an exceptional developer experience.

What is the most important factor in your decision to become an OpenAPI Initiative member?

OpenAPI isn’t just a specification for us: it’s the foundation of our product architecture and business model. Every one of our 200+ unified connectors, every SDK we generate, and every validation we run starts with an OpenAPI contract. It’s the backbone that made our entire business possible, and frankly, we wouldn’t exist in our current form without it.

That’s why joining OAI feels like closing the loop. We’ve been adopters for years, building on top of this incredible standard. Now it’s time to become active contributors: to give back to the ecosystem that enabled everything we’ve built, and to help shape how the next generation of APIs and AI agents communicate. As standards become increasingly critical in the AI agent revolution, we want to be at the table, ensuring OpenAPI evolves to meet these emerging needs.

How would you like to see the OpenAPI Specification evolve in the future?

We’d like to see the specification evolve to better support API aggregation, normalization, and unification challenges. As a unified API company, we deal with the full spectrum of API quality and need specifications that can handle complex scenarios. The specification should also prioritize AI-readiness with enhanced semantic clarity about what each API operation actually does, making it easier for AI agents to understand and interact with APIs programmatically.

Do you use Arazzo, and if so how important is Arazzo’s development in expanding how APIs are described?

Arazzo’s development for orchestrating complex multi-API workflows is particularly relevant to us as a unified API company. When you’re normalizing hundreds of APIs across dozens of categories, workflow orchestration becomes critical. We’re already putting Arazzo to work: using it to auto-generate tests for our SDKs across 6 languages, ensuring that our implementations handle multi-step workflows correctly and consistently.

We see Arazzo as an important evolution in describing not just individual APIs, but how they work together in real-world integration scenarios. This matters even more in the context of AI agents, which need to chain multiple API calls together to accomplish complex tasks. Having a standard way to describe these orchestrations will be essential for both human developers and autonomous agents.

Do you use Overlay, and if so how important is creating standardized automation languages for OpenAPI descriptions?

Yes, we use Overlay extensively in our SDK generation process. It’s become critical for us to inject different SDK examples and generate different flavors of OpenAPI specifications tailored to our various tooling needs. When you’re generating SDKs across 6 languages from a single source OpenAPI spec, having a standardized way to apply transformations and customizations is essential.

We’re also using Overlay to augment and enrich our API descriptions and documentation: layering in additional context, examples, and metadata without modifying the upstream specifications directly. This separation of concerns is invaluable when you’re maintaining 200+ connector specifications that need to stay synchronized with vendor APIs while also being optimized for our unified API layer.

For us, standardized automation languages like Overlay represent the difference between maintainable, scalable tooling and an unmaintainable mess of custom scripts. As OpenAPI becomes the lingua franca for API-first development and AI agent interactions, having robust, standardized ways to transform and augment these descriptions programmatically isn’t just important: it’s foundational to building reliable automation at scale.

If you could have one feature included in future versions of the OpenAPI Specification what would it be and why?

It’s not really a feature, but we would like to see an official OpenAPI registry comparable to the MCP server registry recently launched. The API ecosystem desperately needs a centralized, authoritative place where developers and AI agents can discover and access OpenAPI specifications. We’ve actually built our own API search engine, called the API Tracker, precisely because this gap exists. An official OpenAPI registry would take this further, providing verified, up-to-date specifications with quality scores, version histories, and standardized authentication patterns. Just as the MCP registry is accelerating AI integrations, an official OpenAPI registry would accelerate API adoption across the entire ecosystem. It would become the single source of truth for both human developers and AI agents looking to integrate with APIs, dramatically reducing the friction in API discovery and integration.

What role do the OpenAPI Initiative specifications play in the evolution of APIs and AI?

OpenAPI is becoming the standard interface for AI agents to understand and interact with any API. Developers aren’t the only ones reading API documentation anymore. AI agents need machine-readable specifications even more than humans do. They require structured, standardized descriptions to navigate authentication flows programmatically, understand what each operation does, and validate if their API calls are correct. Combined with protocols like MCP (Model Context Protocol), OpenAPI specifications enable AI assistants to not just understand but actually execute API calls in real-time.

Any final thoughts that provide insights on how you use OpenAPI that you feel is of interest to the community?

We’ve open-sourced Portman, our CLI tool that converts OpenAPI specifications into Postman collections with automated contract testing. With 600+ GitHub stars and 25+ contributors, it shows how OpenAPI can be leveraged beyond documentation to create powerful testing workflows. This demonstrates our belief that open standards and open-source tools reinforce each other. Standards enable better tools, tools validate standards, and the community amplifies the impact of both. We encourage other API companies to not just adopt OpenAPI but to contribute their tools and learnings back to the ecosystem.

Contributors: Gertjan De Wilde, Kateryna Poryvay, Saurabh Rai

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:

How to contribute guide.
Our Specifications homepage, with the latest versions of OpenAPI, Arazzo, and Overlay.
OpenAPI Initiative on GitHub, where we develop our specifications.

About the OpenAPI Initiative

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.

To learn what OpenAPI can do for you please visit our What is OpenAPI page.

About Linux Foundation

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

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.

Sep 26

The OpenAPI Initiative Welcomes Jentic!

By Chris Wood Blog

We are pleased to welcome Jentic to the OpenAPI family! Jentic joined the OpenAPI Initiative in early 2025, and 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.

We talked with Erik Wilde, Head of Enterprise Strategy for Jentic and, of course, OAI Ambassador and lead for the OAI Track!

Thank you Erik for taking the time to talk to us!

Please tell us a bit about your organization and your needs as an API provider in publishing well-described APIs.

Jentic is using APIs in two ways: The first is by building on existing APIs and providing a layer of workflows on top of these APIs which can be used by agents. This allows agents to use targeted, repeatable, and efficient workflows. The second way of using APIs is by exposing the workflows themselves as APIs, so that they can be used throughout the entire organization like any other API.

What is the most important factor in your decision to become an OpenAPI Initiative member?

Jentic uses OAI’s open standards as the very core of our platform. Like so many other organizations, we need those standards to be robust, and we need a healthy ecosystem to be in place to maintain and evolve these standards. For Jentic, supporting OAI means to support the very foundation that our business is built on, and it also means to support the growing ecosystem of API users out there who need OAI to be successful with their API and AI initiatives.

How would you like to see the OpenAPI Specification evolve in the future?

For now, OpenAPI itself is established and very stable, and while we look forward to OpenAPI 3.2 and beyond, OpenAPI itself is a great foundation as it is. Our focus is a bit more on Arazzo, but I guess that’s covered in the next question…

Do you use Arazzo, and if so how important is Arazzo’s development in expanding how APIs are described?

For us, Arazzo is less expanding how APIs are described, but more expanding the space which is covered by open standards. We see it as an extremely relevant and powerful addition to the API space. Ideally, we would like to see Arazzo extending beyond orchestrating OpenAPI APIs. We know that AsyncAPI is in the pipeline, and it would be interesting to look beyond that and explore how Arazzo can pull in as many APIs as possible, regardless of how they are described.

Do you use Overlay, and if so how important is creating standardized automation languages for OpenAPI descriptions?

So far, Jentic is not using Overlay, but we are looking at it and are excited by its possibilities. One area that we are looking at is applying overlays to Arazzo: Since we describe our workflows in Arazzo, it could be interesting to support different views of these workflows, in the same way as Overlay supports different views of an OpenAPI-described API.

If you could have one feature included in future versions of the OpenAPI Specification what would it be and why?

Since APIs will be increasingly consumed by AI, directly or indirectly, it would be great to see OpenAPI supporting the needs of this class of consumers a little bit better. This does not necessarily mean that any new functionality is needed, it may just be that the richness of the descriptions could be improved for AI consumers. Currently, nobody exactly knows what this could look like, but it would be great to see this class of consumers being considered in updates to the specification.

What role do the OpenAPI Initiative specifications play in the evolution of APIs and AI?

OAI and OpenAPI play essential roles in the evolution of APIs and AI. The entire API is bigger than just OAI’s specifications, but their market share is big enough that any progress or lack thereof has a notable impact of how the API space evolves. When it comes to AI and specifically AI agents, APIs play an absolutely critical role: AI Agents must be able to gather input and perform actions, and without APIs, this is impossible. Many of the APIs that AI agents are using will be described in OpenAPI, which makes it obvious how critical the role of OAI’s specifications is.

Any final thoughts that provide insights on how you use OpenAPI that you feel is of interest to the community?

We firmly believe in the power of standards. They provide a shared model and terminology, and they create a rich ecosystem of practices and tooling. Using open specifications as your source of truth, and focusing on the quality of the descriptions that you create, will become more important than ever. The API space, which has been around for a little longer, and the newer AI space will grow closer and closer, and using standards as the connective fabric is the winning strategy in the increasingly complex digital world that we are living in.

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:

How to contribute guide.
Our Specifications homepage, with the latest versions of OpenAPI, Arazzo, and Overlay.
OpenAPI Initiative on GitHub, where we develop our specifications.

About the OpenAPI Initiative

To learn what OpenAPI can do for you please visit our What is OpenAPI page.

About Linux Foundation

Contributors: Erik Wilde, Chris Wood

Sep 23

Announcing OpenAPI v3.2

By Chris Wood Blog

We are delighted and proud to announce the release of v3.2.0 of the OpenAPI Specification!

Our latest minor version brings a host of new features across a number of areas including supported HTTP methods, a new tag structure, support for streaming media types, and a whole lot more!

Here’s a quick rundown of the headline features.

Multipurpose Tags with Nesting

One of the most significant changes, particularly for rendering a graphical view of an OpenAPI description, is the change to the Tags object. The new Tag Object structure introduces summary for short descriptions, parent for nesting, and kind for classifying Tags, allow a taxonomy to be developed, supported by a registry of commonly supported values.

kind is useful because it allows tooling to selectively include and ignore Tags when parsing an OpenAPI description, as shown in the example below.

tags:
# Only used for rendering

  – name: products
    summary: Products
    description: All product operations
    kind: nav

  – name: books
    summary: Books & Literature
    description: Book catalog and recommendations
    parent: products
    kind: nav

# Used for grouping Badge related operations in generated code

  – name: digital-delivery
    summary: Digital Delivery
    description: Instantly delivered digital products
    kind: badge

Tags can therefore be created for different purposes, making the structure of the Tag Object much more flexible.

As you migrate to v3.2.0, be sure to contribute to the Kind registry to share useful Tags across the community!

HTTP Method Changes

v3.2.0 also includes a number of new features for more advanced HTTP method support.

Firstly, the new version offers built-in support for the query HTTP method. query provides support for safely querying the state of a resource in an idempotent way using a query payload. You can therefore define more complex query terms in your OpenAPI descriptions, with support from Schema Objects, with a separation from post methods that you might have used in the past for such operations.

Support for other HTTP methods that are not first-class citizens in OpenAPI is now provided by the additionalOperations. You can define a Map of HTTP methods you choose to include in your API design, and that can be processed by tooling, that are implemented as standard Operation Objects:

paths:
  /:
    additionalOperations:
      connect:
        operationId:
          ## A standard Operation Object

The other major enhancement is the introduction of querystring, which provides the means to define all query parameters as a Schema Object, allowing for greater control in defining how query parameters are defined and coexist in a given API operation.

Sequential and Streaming Data

A welcome addition in this version of OpenAPI is increased 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.

OpenAPI now supports the following types:

Server-Sent Events: text/event-stream
JSON Lines: application/jsonl
JSON Sequences: application/json-seq
Multipart Mixed: multipart/mixed

These types work in tandem with the itemSchema keyword, which defines what a streamed event looks like over the wire. The addition of this support is a significant enhancement for both understanding streaming APIs and for tooling makers who typically need to ingest many different data structures, represented by many Schema Objects, through a single Operation.

New Security Features

There are also a number of new features in Security.

v3.2.0 introduces support for OAuth 2.0 Device Authorization Flow. Device Authorization Flow is an OAuth profile that supports End User authorization on limited input devices – think smart TVs and kiosks – and therefore requires a specialized flow to cater for handoff to an input device. Given the proliferation of such limited input devices providing support for Device Authorization Flow is a real boost for API Providers bringing their APIs to broadcasting platforms.

The core OAuth Flow object has also been enhanced to include the oauth2MetadataUrl property, which defines a URL at which OAuth 2.0 Server Metadata can be retrieved, supporting OAuth flows. Providing links to metadata, in the same way as the OpenID property openIdConnectUrl allows an OpenAPI description to be a key reference point for API Consumers, providing both functional and security information. Such reference points are particularly important in sectors like open finance, which rely heavily on publishing OAuth and OpenID Connect metadata for automatic discovery of services.

Other Features

We’ve only covered some headline changes here, in an effort to bring together the most impactful changes in this release.

For more details please review:

The Specification page for v3.2.0.
The Release Notes on GitHub, which provides a headline list of all changes.
Our Learn site, where you’ll find a migration guide.

As ever, our thanks and appreciation go to our great community members who worked so hard to bring this version together! Special thanks go to Henry Andrews and Lorna Mitchell for their significant contributions to this effort!

Contributors: Lorna Mitchell, Chris Wood

Aug 29

Why Do We Run the OAI Track?

By Chris Wood Blog

Summer is nearly over in the northern hemisphere, we are three-quarters of the way through 2025, and already we’ve had great attendance at our OpenAPI Initiative (OAI) Track at Apidays New York, Helsinki, Munich, and DeveloperWeek San Francisco. We still have API:World Santa Clara, and Apidays London, and Paris to come this year, with our dedicated stage and all day track at API:World!

With all these events past and planned, it seems like a good time to take stock and restate why we do the OAI Track.

Community Engagement

The first “why” seems pretty obvious. The Specifications that fall under the OAI banner – OpenAPI, Arazzo, and Overlay – lead the API community in providing standardized, interoperable foundations for building and consuming APIs. The OAI Track gives us a forum to connect directly with the global community, strengthen collaboration across industries, and create a shared understanding of the role open standards play in shaping the API economy. It is also a space where newcomers to the community can learn, ask questions, and find ways to get involved.

Showcasing OpenAPI

The OAI Track also attracts some great speakers, with an increasing number of sessions covering the intersection between AI and OpenAPI. APIs being the bedrock of successful AI-strategies and repeatable AI outcomes, with well-described APIs being the most usable in AI applications and use cases in their current form. The narrative on OpenAPI in the AI world is still being written, with many success stories of how organizations are embracing AI in creating, consuming, and using API descriptions created in OpenAPI. The first release of Arazzo has also coincided with new protocols like Model Context Protocol, which in itself demonstrates the need for describing API-based workflows for both humans and machines, which Arazzo natively provides.

The OAI Track gives us a platform to highlight not just the specifications themselves, but the wide variety of real-world implementations, case studies, best practices, and emerging opportunities. This is a chance for practitioners to share lessons learned, for tool builders to demonstrate innovation, and for the wider community to see the tangible impact of the OAI specifications in action.

Creating a Feedback Loop

Just as important as showcasing is listening. The OAI Track creates a structured opportunity for direct feedback from the developer and practitioner communities. We learn insights on where the specifications are helping, where they could be clearer, and what gaps remain. This feedback goes to the heart of the development efforts, with specification contributors like Frank Kilcommins and Lorna Mitchell regularly leading or presenting at the OAI Track.

By turning this feedback into tangible improvements in our specifications the OAI ensures that specifications evolve in a way that reflects the needs of the people who depend on them most. Hearing from the community directly is vital to evolving the OAI Specifications in a way that meets the needs of the people who depend on it most.

What’s Next for the OAI Track

The OAI Track will continue to grow with this very successful format being taken forward into 2026. We are also holding breakfast sessions at Apidays London and Paris specifically focused on what it means to be an OAI member, and how we are changing our membership in the future.

Hope to see you at the OAI Track soon!

Contributors: Erik Wilde, Frank Kilcommins, Chris Wood.