Skip to main content
All Posts By

OpenAPI Initiative

Why the Largest Geospatial Organization in the World Uses the OpenAPI Specification

By Blog

The Open Geospatial Consortium (OGC) recently announced that OGC API – Tiles was adopted as an official OGC Standard. The OGC is a collective problem-solving community of experts from more than 500 businesses, government agencies, research organizations, and universities representing hundreds of thousands of geospatial professionals driven to make geospatial (location) information and services FAIR – Findable, Accessible, Interoperable, and Reusable.

The OGC API - Tiles Standard defines building blocks for creating Web APIs that support the retrieval of geospatial information as tiles. Different forms of geospatial information are supported, such as tiles of vector features (“vector tiles”), maps, imagery, and other types of geospatial information.

The new standard focuses on simple reusable REST API building blocks that can be described using the OpenAPI Specification.

Dr. Gobe Hobona, is the Director of Product Management, Standards at Open Geospatial Consortium (OGC). 

Dr. Hobona joined OGC Staff in 2017, having been an OGC member since 2004. As the Director of Product Management, he provides oversight of the development of OGC API Standards, managing releases, and product marketing.

Who uses the Open Geospatial Consortium and why? Can you give an example?

Standards by the Open Geospatial Consortium are used by hundreds of organizations to publish millions of datasets, as reported by GeoSeer.net. Many of the organizations are OGC Members that all actively participate in a consensus process that designs and publishes standard specifications which improve interoperability. A few of the domains that make use of OGC Standards are Aviation, Built Environment & 3D, Business Intelligence, Government & Spatial Data Infrastructure, Energy & Utilities, and many more. 

A great example of those standards being used would be in the aviation industry like EUROCONTROL, the European Air control agency and the Federal Aviation Administration (FAA) in the United States. Those teams publish a lot of their data using OGC Standards, specifically the Geography Markup Language (GML) which they have implemented in the Aeronautical Information Exchange Model (AIXM). Another example of the use of the standards is the OGC API – Features Standard which has been adopted as a Good Practice for implementing download services that are compliant with the European Union’s INSPIRE Directive, which positively affects hundreds of millions of EU citizens across the continent.

What’s new about the release of OGC API – Tiles? How will this be used? Who should use this?

We are really excited about it. The OGC API – Tiles Standard has been in the works for a number of years and now it is here. The OGC API defines building blocks for creating Web APIs that support the retrieval of geospatial information in tiles, basically little image chips that can be streamed with nearby chips to show a map. There are many great things about it, some special features include map tiles and vector tiles. Rather than the end user having to retrieve a large data set for the whole world, they can just retrieve that single tile. They can then use the identifier for that tile to collaborate with colleagues. Those in environmental sciences might retrieve a tile from other specialties and vice-versa. Now, instead of transferring terabytes of data across a network, it is just a subset. 

We have standardized models for Tile Matrices, we have a registry where various organizations can agree on a set of tiling schemes to use together. There have been significant efficiency and cost savings seen across the board. Transmitting complete datasets over a network can incur some charges, so transmitting only relevant subsets offers cost savings. Also, performance has improved. For tiles that do not change, it is now possible to provide a cached tile. We recently hosted a code sprint in Brussels where developers came together from across the globe, and within a short time they were able to implement this standard, and simply just used the implementations through various client applications. 

I’ll point out, all of that was made possible because the OGC API – Tiles Standard uses the OpenAPI Specification, which makes it attainable for web components to describe the capabilities for the resources, schemas, and so much more. In the previous generation of web service standards, it required developers to interpret the requirements of a standard. Now it is possible for some of that role to be done by the applications themselves. Apps can interpret what the API is intended to do. This takes away the burden from the developers and it leads to very happy developers!

What is the advantage of open source with spatial information?

Open standards by the OGC are used by both open source and proprietary software products; they do that to make Geospatial information more findable, accessible, interoperable, and reusable. One key thing about open standards and open source software is that they reduce the risk of vendor lock-in. With vendor lock-in, an organization gets tied to a single vendor and they must obtain products from that vendor. With open standards and open source software, it certainly reduces the risk of this and organizations do not have to buy from a single vendor. Furthermore, some common parts of commercial software come from open source to reduce the cost of developing some of that fundamental technology that can be shared; for example, the open source GDAL library is used by several commercial software products.

Why do you support the OpenAPI Specification? What are the main advantages?

The OpenAPI Specification makes it possible for developers to automatically create source code through code generators, by simply parsing an API definition document that complies with the OpenAPI Specification. In the past, most creation of source code required developers to manually read and interpret API definition documents, which led to human error and was certain to take longer to implement interfaces. Now, a lot of the interpretation is done by the application and then the human developer joins to codify the business logic. Moreover, using OpenAPI means that all of our APIs are defined in a consistent way so that the use of the APIs is predictable for all developers.

The efficiency gain for an organization is incredible. It is one of the key reasons why the OpenAPI Specification has been looked upon favorably by the OGC community.

OGC develops open standards, so everyone has the opportunity to provide some input to the standards. Other organizations do not have to wonder if there are some restrictions to access to the standards. But also, organizations can feed requirements in, as a community both the OGC and the Linux Foundation, which houses the OpenAPI Initiative and looks after the OpenAPI Specification, have done an excellent job of involving everyone across industry. There is a lot of feedback that is included or at least considered in the design of those standards. Everyone in the community has a chance to include input into those standards.

What is the best way to get involved in the OGC?

The OGC runs three member meetings a year, in different parts of the world, and with hundreds of participants. Now that travel restrictions are easing up, those meetings are now hybrid meetings with remote participants being supported. 

OGC working groups use those meetings to gather needs and specs. In between those meetings, there are a series of working group get-togethers. For anyone that is interested in participating, I would recommend going to the OGC website and have a look at the information about membership, there is also a list of working groups. We have domain working groups in defense, aviation, meteorology, and more. We also have other working groups that focus on specification, like OGC API – Tiles and OGC API – Features.  

The next OGC meeting will be from 20th to 24th February 2023, hosted by the European Space Agency in Frascati, Italy. That will be the first of three taking place in 2023, there will be another in June in Huntsville, Alabama, and another in September in Singapore.

I would also like to mention, the OGC runs several initiatives, we run innovation initiatives, where members can join in. These are run by the Collaborative Solutions and Innovations team in OGC, those initiatives are funded by the OGC membership, and they provide an opportunity for research and development. I encourage anyone interested to look at the OGC website and participate in these activities. 


OpenAPI Resources

To learn more about participating in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) 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. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

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 linuxfoundation.org.

Bump.sh, API Contract Management Platform, Joins the OpenAPI Initiative

By Blog

The OpenAPI Initiative, the consortium of forward-looking industry experts focused on evolving and implementing the OpenAPI Specification (OAS), is announcing that Bump.sh has joined as a new member. Welcome!

Bump.sh is an API contract management platform that helps document and tracks APIs: identifying what changes in APIs structure, and keeping developers up to date across an organization. Bump.sh acts as a single source of truth with information that remains up to date and changelogs.

The company has raised $4 million in funding led by Galion.exe and Bpifrance’s Digital Venture fund. 

“We believe schemas are the cornerstone of future-proof API development. As a vendor, it is our duty to contribute to and keep up to date with the latest specifications,” said Sébastien Charrier, CEO of Bump.sh. “Joining the OpenAPI community will help us better support our customers and contribute to the direction of OpenAPI Specification development.”

To learn more about Bump.sh, please visit: https://bump.sh/ 

Want to become a member of the OpenAPI Initiative? Find more information here: https://www.openapis.org/membership/join 

OpenAPI Resources

To learn more about participating in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

●   Become a Member

●   OpenAPI Specification Twitter

●   OpenAPI Specification GitHub – Get started immediately!

●   Share your OpenAPI Spec v3 Implementations

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) 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. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

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 linuxfoundation.org.

Noname Security, API Security Company, Joins the OpenAPI Initiative

By Blog

The OpenAPI Initiative is announcing today that Noname Security has joined as a new member. Welcome!

According to recent research commissioned by Noname Security, API Security Trends in 2022, 76% of those surveyed reported they had experienced an API security incident in the past 12 months. Noname covers API security across three pillars: posture management, runtime security, and API security testing. Noname Security is privately held, remote-first with headquarters in Silicon Valley, California, and offices in Tel Aviv and Amsterdam.

Noname works with 20% of the Fortune 500 and has won numerous security awards.

“As we continue our rapid growth, joining the OpenAPI Initiative brings immense value in bolstering every aspect of our platform from posture management to API security testing,” said Shay Levi, Co-Founder and CTO of Noname Security. “We are excited to be part of the OpenAPI Initiative and look forward to better serving our customers and their critical assets by supporting this vendor-neutral open source specification and ecosystem.”

To learn more about Noname Security, please visit: https://nonamesecurity.com/  

Want to become a member of the OpenAPI Initiative? Find more information here: https://www.openapis.org/membership/join 

OpenAPI Resources

To learn more about participating in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

●   Become a Member

●   OpenAPI Specification Twitter

●   OpenAPI Specification GitHub – Get started immediately!

●   Share your OpenAPI Spec v3 Implementations

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) 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. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

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 linuxfoundation.org.

ASC 2022 in San Francisco 🌉 by the Numbers

By Blog

This year’s API Specifications Conference (ASC), organized by the OpenAPI Initiative, set a record for submissions for talks, won the CHAOSS Gold badge for Diversity and Inclusion, was rated excellent or above by 95% of the attendees, and was an excellent networking opportunity and… was just plain a lot of fun!

ASC 2022 was held in person in South San Francisco, California, from September 19 – 21. Due to Covid restrictions and as a precaution the conference was held virtually for the past two years. This year, it was hybrid. No matter the format, the conference continues to be extremely popular and showcases developers, users, companies, organizations, API tool makers and more, all interested in API technology.

It was a real thrill hearing from and interacting with industry experts discussing topics such as OpenAPI Specifications, RAML, Blueprint, gRPC, OData, JSON, Schema, GraphQL, AsyncAPI, and other formats. 

Recordings are available here (on-site) and here (virtual).

 The full Linux Foundation report on ASC 2022, “Transparency Report: API Specifications Conference (ASC),” (PDF) is available for download.

The ASC 2022 received the CHAOSS Gold badge, a Linux Foundation project, for the second year in a row! The CHAOSS Gold badge was awarded because ASC 2022 met greater than or equal to 80% of requirements in the open source community that fosters healthy Diversity and Inclusion (D&I) practices.

Other inclusion efforts included: Offering onsite resources like a quiet room if you need a physical space where conversation and interaction are not allowed, a nursing room and child care as well as special communication stickers, and other features to make this event as accessible as possible.

The Keynote speakers presented on a wide variety of API topics including Near Realtime, Autogenerated API Specs for Fun and Profit by Jean Yang, CEO Akita Software; Building APIs at Scale: Moving from API Governance to API Stewardship by Mike Kistler & Mark Weitzel;  Microsoft, the Retrospective Panel moderated by Kin Lane, Postman and including Lorinda Brandon, BetterCloud and including Gareth Jones, Microsoft, Ole Lensmar, Kubeshop, Tanya Vlahovic, Salesforce; and The Spec At Twitter by Daniele Bernardi, Twitter. 

Special thanks to Frank Kilcommins, API Technical Evangelist, SmartBear, for welcoming and giving the Opening Remarks.


Attendance by the numbers!

The survey conducted after the conference showed that 95% rated the content as great or excellent (4 or above on a scale of 1-5) ⭐️⭐️⭐️⭐️⭐️! 45% of attendees say they attended ASC 2022 as a valuable way to meet people in the industry or network.

We had an attendance of 123 people from 17 countries.🌎

Record CFP Submissions! 🔥

The API Specifications Conference (ASC) 2022 received 111 CFP submissions, compared to 104 in 2021, 72 in 2020, and 42 in 2019. A team of peer reviewers accepted 44 sessions. Program Chair, Frank Kilcommins of SmartBear, along with the planning committee, carefully curated content and the keynote lineup bringing the most relevant topics and talks to this year’s event.

For those that missed the conference or would like to watch the event again, the keynote and session recordings are available on our YouTube Channel.

Download the full Linux Foundation report on ASC 2022 here: “Transparency Report: API Specifications Conference (ASC)” (PDF) is available for download.

First Time Ever! OpenAPI Track at APIDays Paris – Join us!

By Blog, Events

The OpenAPI Initiative is hosting an OpenAPI track at APIDays Paris on December 14, 2022. 

To register, see: https://www.apidays.global/paris#agenda 

As a member of the OAI community, you can register with a complimentary pass using the code OAI20. Only 20 are available, so don’t wait!

This all-day track focused on OpenAPI Specification issues is a first and will include a wide variety of API topics of interest to both developers and managers. It is intended to become a series of one-day events at APIDays events planned for 2023. 

View Full Schedule

The goal of the OpenAPI track is to bring API practitioners together and share real-world experiences. How are you using the OpenAPI Specification in your company? What are the main strengths and weaknesses? At the end of the track, we will meet to discuss the specification, its evolution, and where it is headed. We will gather feedback from you to bring back to the OpenAPI initiative. 

If you are using the OpenAPI Specification in your company and have something to share, please make sure to attend the Community Feedback OpenAPI session starting at 16:55.

The day includes presentations from Isabelle Mauny, Co-Chair at OpenAPI Initiative, on The State of OpenAPI; from Steve Swartz, Principal Architect at Cisco, on The 12 Facets of the OpenAPI Specification; from Beppe Catanese, Developer Advocate at Adyen, covering From API Specifications to Code with OpenAPI; and from Mario Bodemann, Developer Evangelist at Deutsche Telekom, on OpenAPI: Building an Android Parser and Tester App… and many more!

 

👋 Come join us! To register, see: https://www.apidays.global/paris#agenda

Cisco Joins OpenAPI Initiative

By Blog

OpenAPI Initiative continues strong pace of membership growth; 45 current members include Atlassian, Bloomberg, eBay, Google, IBM, Microsoft, Oracle, Postman, SAP, SmartBear, and many more

SAN FRANCISCO – October 18, 2022 – The OpenAPI Initiative, the consortium of forward-looking industry experts focused on creating, evolving, and promoting the OpenAPI Specification (OAS), a vendor-neutral, open description format for RESTful APIs, is announcing today that Cisco has joined as a new member.

As a catalyst in community-powered innovation in cloud native development, AI/ML, API security, connectivity, observability, network automation, and more, Cisco believes that standardizing Web APIs throughout the cloud will provide transparency and value across the global open source and cloud native community ecosystem. Cisco sees the advantages of implementing the OpenAPI Specification to address cloud native challenges, reduce implementation costs, and support the next generation of visionaries through open source.

“Well-built components are a core consideration in shipping powerful applications and platforms,” said Stephen Augustus, Head of Open Source, Cisco. “Cisco is thrilled to join esteemed partners in the OpenAPI Initiative to drive innovation and wider adoption of the OpenAPI Specification as a fundamental component for robust, interoperable applications.”

“We are excited to welcome Cisco to the OpenAPI Initiative. Cisco is active with many open source and Linux Foundation projects, so it is a natural fit, and we look forward to working more closely with them to build the OpenAPI Specification,” said Kevin Swiber, Marketing Chair, OpenAPI Initiative and API Lifecycle Integration Specialist at Postman. “Our membership is open to anyone who understands the immense value of standardizing APIs and is interested in evolving and promoting a vendor neutral description format. Why not become a member and get started today?”

Want to become a member of the OpenAPI Initiative? Find more information here: https://www.openapis.org/membership/join 

OpenAPI Resources

To learn more about participating in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

●   Become a Member

●   OpenAPI Specification Twitter

●   OpenAPI Specification GitHub – Get started immediately!

●   Share your OpenAPI Spec v3 Implementations

About Cisco Open Source

Cisco has a long history in the open source and standards ecosystems, with community-powered innovation in cloud native development, AI/ML, API security, connectivity, observability, network automation, and more. To find out more about Cisco’s open source activities: opensource.cisco.com 

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) 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. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

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 linuxfoundation.org.

ASC 2022 Community Partner Sponsorships Free to Members!

By Blog

Join us at The API Specifications Conference (ASC) this September 19-21 in South San Francisco! ASC 2022 is a place for API practitioners to come together and discuss the evolution of API technology. ASC includes cutting edge technology keynotes and sessions that chart the future of APIs, in-depth specification, and standards discussions. 

The event is designed to be highly interactive with plenty of discussion time throughout the workshops and sessions! 

Want to sponsor ASC 2022 but thought it was too much for your budget? Think again!

Community Partner Sponsorships are available for free for OpenAPI Members or $500 to non-members. (If you want to learn more about becoming a member of the OpenAPI Initiative, go here.) This partnership is a great opportunity to connect directly with API practitioners including API developers, API Operations teams, API Designers and Enterprise Architects. 

Deadline to sign up is Aug 19th. 

All Community Partner Sponsors will benefit from the following:

  • Display on shared table in sponsor showcase
  • Logo included in “Thank You to our Sponsors” keynote slide
  • Logo included in “Thank you to our Sponsors” blog post 
    • Will be posted prior to the event on OpenAPI blog
  • Recognition on event website (prominent logo display on event homepage)
  • Post-Conference Data Report: Provides event demographics and additional details on event performance

Become a Sponsor!

APIIDA, Delivering Automated API Management Solutions, Joins the OpenAPI Initiative

By Blog

The OpenAPI Initiative, the consortium of forward-looking industry experts focused on evolving and implementing the OpenAPI Specification (OAS), is welcoming APIIDA as a new member.

APIIDA provides an API management platform and develops solutions and products for customers to manage change by enabling technology-independent API management. The APIIDA solution separates APIs from their runtimes and adapts them to focused strategies, acting as independent entities. This is done with the goal to improve customer experience and allow the rapid growth of new business models and offerings. 

“We are excited to be a part of the OpenAPI Initiative. Having widely adopted standards like OpenAPI provides us with a stable base we can build upon. Together with the other members of the OpenAPI Initiative, we want to expand the reach and the adoption of the OpenAPI Specification. This will benefit APIIDA customers, and it’s the right thing to do for the broader API community,” said Markus Müller, CTO, and co-founder of APIIDA. “By actively contributing to the special interest groups and the steering committees we want to give back to the community.”

The company currently serves over 300 organizations of all sizes and across a wide range of industries. 

Want to become a member of the OpenAPI Initiative? Find more information here!

APIIDA Resources:

OpenAPI Resources

To learn more about participating in the evolution of the OpenAPI Specification: 

https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing 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. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

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 linuxfoundation.org.

Karate Labs, Testing Automation Framework, is Joining the OpenAPI Initiative

By Blog

The OpenAPI Initiative, the consortium of forward-looking industry experts focused on evolving and implementing the OpenAPI Specification (OAS), is announcing that Karate Labs has joined as a new member.

5900 GitHub stars | Used by Fortune 500 companies worldwide 

Karate Labs is an open-source solution unifying API & UI test automation including mock-servers and performance testing. Karate’s core of API testing includes sophisticated payload data and schema validation, and a unique capability to re-use API tests as performance tests.

Karate Labs API data importer enables teams to import all leading sources of API data and to preview, edit and export the API sequence using an intuitive no-code user experience.

“With more teams adopting the OpenAPI Specification as a standard, we see the opportunity to align test automation efforts and further accelerate adoption. We are excited to join the OpenAPI Initiative to deliver even more value to our customers,” said Kapil Bakshi, co-founder, and CEO of Karate Labs. “With software products depending more than ever on APIs, the OpenAPI specification has injected more rigor and collaboration into how APIs are designed, implemented, and consumed. Karate Labs aims to simplify test automation for business stakeholders, product owners, and QA specialists.” 

OpenAPI Initiative is always welcoming NEW MEMBERS, find more information about becoming an OpenAPI member here!

Karate Labs Resources:

OpenAPI Resources

To learn more about participating in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) 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. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

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 linuxfoundation.org.

OpenAPI v3.1 Resources for Tooling Developers 

By Blog

This post is authored by Phil Sturgeon, Green Tech consultant at Green Turtle, and Chairperson, Protect Earth. If you’d like to donate to Phil’s charity of choice, please see Protect Earth which is reforesting the U.K. one field at a time.

OpenAPI v3.1.0 has a bunch of great changes, solving problems like the subtle differences between JSON Schema objects and OpenAPI Schema objects, and adds support for Webhooks.

Upgrading tooling can be tricky, but this should be a lot easier than the jump from v2 to v3.0. To reduce the workload we’ve put together some convenient resources for tooling developers, to provide test cases, examples, and guidance in general.

First of all, these articles will show the differences between v3.0 and v3.1 from a user perspective:

Do you need to support everything?

Some of that content is aimed more at end users and what they will need to do, but what do tooling vendors need to do?

For new features like webhooks, you can think to yourself: does this tool need to support webhooks? If it’s a documentation tool, probably! If the tool is validating incoming web requests to your server, then probably not.

Some tools have gone with a definition of 3.1.0 support which is “a 3.1.0 document will work equally well as a 3.0.0 does in the same tool”, which is a good first step. Then support for other new keywords can be added later.

It’s my opinion that getting 3.1.0 documents to work at a basic level is more important than supporting every single feature in 3.1.0. End-users will create feature requests for the bits they’re most excited about as you go.

JSON Schema consolidation

For the bulk of the other changes, the difference is that instead of using a schema object that is very similar to JSON Schema, the OpenAPI Schema object is now literally JSON Schema. There’s some technicalities involved here and technically OpenAPI Schema has defined it’s own JSON Schema vocabulary, which extends the main JSON Schema vocabulary and adds support for discriminator. As the usage of discriminator in 3.1.0 was clarified to be purely a “hint” or shortcut for an existing oneOf, anyOf, allOf, this can be safely ignored by the vast majority of tooling.

tl;dr: you can use any valid JSON Schema tooling to work with the contents of a schema: object in OpenAPI, which means a lot of tools can phase out reliance on hand-crafted schema inspection code, and leverage any of the existing JSON Schema tooling instead.

For example, if a tool you maintain was manually validating OpenAPI Schemas in JavaScript before, it might be an idea to wrap that in an if ($version == "3.0") statement, use that old logic, deprecate it, then if the version is 3.1 you could leverage powerful tools like AJV or HyperJump to do all the heavy lifting. This immediately benefits your tooling from them doing all the work supporting modern JSON Schema / OAS3.1 keywords for you, like if/then/else.

It also means they can do the heavy lifting for other changes that come as JSON Schema matures into a stable release (although it would be brilliant if you could help them out a too).

Test Cases

To make sure your tooling works with OpenAPI v3.1, you’ll need some OpenAPI v3.1 documents to test against. There is no official list of OpenAPI v3.1 documents around, but there are some example files written by the community which can be used in a test suite to show pass or fail scenarios:

Validation Schema

Many tools use a JSON Schema document that describes valid OpenAPI documents. Yes that is a very meta sentence, but if you know what I mean then you are wondering if there is a new one for OpenAPI v3.1? Good news, there is!

Find Other v3.1 Tooling

To see how other OpenAPI tools are doing take a look at OpenAPI.Tools. Perhaps there is some other tooling you could leverage, or some developers you could team up with, or ask questions to, or hire to work on your thing too, etc.

Don’t forget to send a pull request to OpenAPI.Tools to say when you’re supporting v3.1, by adding v3_1: true to _data/tools.yml. You can also pop a openapi31 tag on GitHub so that other tooling aggregators can find you too!

Expand allBack to topGo to bottom