THE LINUX FOUNDATION PROJECTS
Tag

Arazzo

Feb 10

OpenAPI Initiative Newsletter – February 2026

By Blog

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

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

Initiative News

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

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

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

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

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

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

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

Events News

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

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

Frank Kilcommins at Apidays Paris 2026
Frank Kilcommins at Apidays Paris 2026 Talking Arazzo and AI Agents

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

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

Ecosystem Spotlight: Jentic AI-Readiness Scorecard

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

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

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

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

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

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

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

Finally

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

Until next time!

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

Dec 04

OpenAPI Initiative Newsletter – December 2025

By Blog

OpenAPI Initiative Newsletter – December 2025

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.

Until next time, and happy holidays!

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

Oct 01

OpenAPI Initiative Newsletter – September 2025

By 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

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.

May 02

OpenAPI Initiative Newsletter – April 2025

By Blog

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.

Author: Chris Wood

Jan 24

Announcing Arazzo Specification version 1.0.1

By Blog

In 2024, the OpenAPI Initiative set a high bar for activity with the release of new specifications like Arazzo 1.0.0 and Overlay 1.0.0, along with two important patch versions of the OpenAPI Specification: 3.1.1 and 3.0.4. Today, we’re excited to kick off 2025 on a strong note by announcing the release of Arazzo Specification version 1.0.1!

This 1.0.1 patch release introduces updates, clarifications, and expansions that refine the specification without altering its core functionality. While the way workflows are described in Arazzo remains unchanged, this release addresses areas where greater clarity was needed, improves examples for implementers, and corrects minor inaccuracies (as is typical with any initial 1.0.0 release).

Importantly, tooling built for Arazzo 1.0.0 will remain fully compatible with 1.0.1, as the patch release does not include any structural changes. This reflects our commitment to maintaining backward compatibility and supporting frequent, iterative improvements for the specification.

If you’re starting a new project or have the flexibility to upgrade, we highly recommend targeting Arazzo 1.0.1 as your version of choice!

Summary of changes

The 1.0.1 release brings important clarifications, improved and corrected examples, and addresses minor inaccuracies in the initial 1.0.0 release. In addition, we’ve introduced a non-authoritative JSON Schema representation of the Arazzo Specification, making it easier for implementers to validate documents programmatically.

Here’s a quick summary of the notable changes in Arazzo 1.0.1:

  • JSON Schema added for the Arazzo Specification 1.0.x.
  • JSON Schema test suite for validation and compliance.
  • Clarified the allowed types for the retryAfter fixed field within the Failure Action object.
  • Improved clarity around the use of workflowId across the Step, Success Action, and Failure Action objects.
  • Adopted RFC 9110 as the reference for Header Field guidance.
  • Adopted RFC 9110 for payload (or request content) guidance.
  • Fixed inaccuracies and typos in field descriptions within the Step Object and Parameter Object.
  • Removed redundant references to event-based message properties from the Runtime Expressions.

Upgrade process

For most users and tool vendors, no action is required—this patch release introduces only wording changes, clarifications, and corrections, with no structural changes to the specification.

That said, if you publish Arazzo tools or maintain workflows that rely on the specification, we recommend reviewing the release notes on
GitHub to ensure everything aligns with your expectations. While the update should be seamless, it’s always a good idea to double-check for any changes relevant to your implementation.

Looking ahead

As noted earlier, we anticipate relatively frequent updates to the Arazzo specification. To ensure smooth adoption, we recommend that tooling makers avoid locking into a specific patch version of the specification, as all patch releases will remain backward compatible.

Looking ahead, we’re already making significant progress on the upcoming Arazzo 1.1.0 minor release. The primary focus of this release is to introduce support for AsyncAPI, enabling workflows to span APIs that leverage both HTTP and event-driven protocols. This exciting development will expand Arazzo’s capabilities, making it a more versatile and comprehensive solution for modern API ecosystems.

Timeline of Arazzo releases, showing version 1.0.1 at January 2025 and the next release at version 1.1.0 scheduled for mid-2025

Timeline of Arazzo Specification Releases

Acknowledgements

This release would not have been possible without the contributions of our vibrant, community-driven ecosystem. The active engagement and stewardship shown by our contributors continue to inspire and drive the evolution of Arazzo. While it’s not possible to name everyone individually, we want to extend our sincere thanks to everyone who has suggested an idea, raised a constructive issue, opened or reviewed a pull request, or participated in our regular calls or discussions. Your efforts have been invaluable, and we deeply appreciate your support and commitment!

We’d like to give particular thanks to the Arazzo Specification editors, who have worked tirelessly to drive, coordinate, and prepare releases for the specification. A special word of gratitude goes to Jeremy Fiel for his excellent work in providing the JSON Schema for Arazzo, and to Ralf Handl from the OpenAPI Initiative Technical Steering Committee, for his hands-on support and invaluable counsel in improving the infrastructural setup around the specification repository.

Thank you all for making Arazzo 1.0.1 a reality!

Getting involved

There are many ways to get involved with Arazzo and the broader OpenAPI Initiative, and we’d like to hear from everyone who uses Arazzo (or wants to)!

Author: Frank Kilcommins

Jul 25

OpenAPI Community Heroes – Frank Kilcommins

By Blog

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 Specification (OAS), Special Interest Groups (SIG), or across the OpenAPI Initiative.

We are delighted to share our next Community Hero, Frank Kilcommins. Frank has over 15 years of experience in the technology industry, with his roles spanning from software engineering to enterprise architecture. His mission is to inspire, engage with, and support the API community and SmartBear customers across the end-to-end API Development Lifecycle and Management space.

Before joining SmartBear, his most recent roles focused on API-led Digital Transformations and architecture modernization within multinational enterprises. In addition to his roles at SmartBear, Frank is a member of the OpenAPI Initiative Business Governance Board and has spearheaded the new Arazzo Specification for API workflows.

What drives your interest and involvement in the OpenAPI Specification?

APIs are critical to the digital world around us, and it’s an area of tech that I’ve been heavily working on for the last decade. I’m naturally drawn to the resilience and affordances brought by specifications and standards and as a result, I’ve been championing OpenAPI adoption and usage within various jobs engaged with HTTP-based APIs. My initial engagements with the community and OpenAPI Initiative were from a learning perspective (and still are) but over time I’ve been able to support others and contribute back as well.

What do you consider to be your most significant personal contribution to the development of OpenAPI?

I would have to say championing the Workflows Special Interest group and driving the creation of the Arazzo Specification have been my personal highlights.

My contributions on the core spec have been mostly verbal or via the Slack workspace apart from revamping the https://spec.openapis.org site to be multi-spec ready. Within the broader OpenAPI Initiative, I’ve also looked to improve some of the related artifacts and repositories. This includes things like ‘community’ to streamline the information on Special Interest Groups and participation, ‘OpenAPI-Style-Guide’ to have a dedicated barbell logo and usage instructions (yes, it matters 😉), and in a very small way the OAICourses material.

What do you see as the most exciting proposed features of version 4 of OpenAPI?

The structural changes are going to significantly reduce the verbosity of OpenAPI descriptions which is great for humans and machines dealing with large API surface areas. Additionally, the hardening of external referencing and improved multi-document support will make our lives as tooling builders much better, and in turn the developer experience for end-users.

How will the Arazzo Specification benefit the development of the OpenAPI Specification?

Arazzo addresses a very natural problem in aiding the description of deterministic use-case-orientated sequences of calls to APIs, be they in a single OpenAPI description, or spanning multiple. In general, thinking and building software in terms of use cases is what comes naturally to humans, so we predict that Arazzo will help improve the state of API design and design thinking. This niche focus can benefit OpenAPI by reducing the burden of supporting such capabilities both from a core spec perspective as well as that of authors who are currently challenged with trying to embed such associations within markdown or extensions.

Moving forward there is scope/vision for the sharing of components between OpenAPI and Arazzo which will bring another set of benefits to the community.

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

I’m excited by the launch of the Arazzo Specification, and the maturing of the OAI into a multi-specification project under the Linux Foundation. This combined with continued work of the Special Interest Groups will help to drive a more rounded OpenAPI Specification by addressing the needs of the community across industry verticals and specialist topics.

Personally, I would like to see a certification process for specification compliance (some of this being spearheaded by Henry Andrews with the OASComply project). Ensuring tool vendors advertise the compliance levels improves transparency for API practitioners and end-users. Ultimately, it can potential also help speed up the adoption of newer specification versions.

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

The elephant in most rooms right now is AI. It will be interesting to see how AI will consume standards, connect with standards-based APIs, and indeed help humans produce, understand, and consume APIs. The Arazzo Specification, as well as designs for OpenAPI 4, are specifically crafted with AI in mind. For example, Arazzo specifically has the semantic determinism to ensure that API sequence execution can be safely handed off to an AI agent.

The evolution of AsyncAPI into a v3 generation is also one to watch. Future collaboration between OAI and AsyncAPI is natural as in many practical situations those producing or consuming APIs are not limited to a single style.

In other areas, I’m particularly interested in developments within OAuth, the OpenID Foundation for OpenID Connect as well as FAPI. Keeping the financial theme, PSD3 also holds promise with respect to enforcing API standardization and performance. It’s also encouraging to see various governments, including the EU, form opinions on the importance of APIs and put forward opinions on API standards and specifications.

Should more people get involved in developing the OpenAPI Initiative specifications and why?

Absolutely! As I mentioned at the outset APIs are the critical tissue that enables much of the technology around us. If you have an interest or passion in APIs, then the OAI is a community that welcomes participation. Just like any open-source project, involvement and participation comes in many forms and caters for a diverse range of skills.

May 29

Meeting Orchestration Needs with Arazzo

By Announcement, Blog

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

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

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

Using Arazzo API providers can:

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

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

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

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

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

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