Skip to main content
search
Tag

Arazzo

May 02
Love0

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 AI to create a comprehensive catalog of OpenAPI and Arazzo description documents, which are themselves optimized to power intent-orientated workflows in agents. The Repository is now hosting a significant number of descriptions, with over 1000 Arazzo descriptions, like the largest collection available at the time of writing.

Thanks to Sean Blanchfield 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 repositories 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
Love0

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
Love1

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
Love0

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.

Close Menu