Coming out of hibernation...

Photo by Jie Wang on Unsplash

Coming out of hibernation...

New OpenAPI and JSON Schema work for 2024!

Sometimes you start a blog and right as you're getting going, life gets complicated. 2023 involved a lot of changes for me, including a shift in focus from the JSON Schema specification to the OpenAPI Initiative (not to be confused with OpenAI!). It's taken over a year for things to settle enough for me to return to writing, but I'm returning now with a quick peak at what I'm working on now. I'll be exploring these topics more in future posts!

The OpenAPI Initiative

2024 is shaping up to be a very exciting year for OpenAPI, and I'm very much involved in the work to define exactly what the year will look like.

OpenAPI Release Landscape

The OpenAPI world is excited about the plan to publish Moonwalk (OAS 4.0) in 2024, but that's only half of the picture. I am (along with others) advocating for putting a lot of work into the 3.x line, including 3.0.y and 3.1.y patch releases, and a series of small, incremental 3.x releases starting with 3.2.

OpenAPI has developed a reputation for releasing giant changes every three to four years (3.1 qualifies despite being sincerely intended as "minor"). These then take another three to four years to be broadly implemented and adopted. It's produced a bit of understandable grumbling mixed in with the Moonwalk excitement among folks who are just getting to 3.1, or are still on 3.0.

We're hoping to provide a smoother path of increased functionality this time, and we're just getting started reviving and updating our processes for easier participation while we produce multiple releases. I'm excited to figure out what pace of change will work best for the OpenAPI community.


Much of my focus last year was on an OpenAPI Description (OAD) parser intended to accomplish several things:

  • Illustrate how the OpenAPI Initiative interprets the OpenAPI Specification's (OAS) parsing requirements

  • Define a format for the parsed representation that can be used to test parsing compliance

  • Serve as the basis for further work, such as linting, a formal compliance test suite, or possibly automated upgrading from 3.x to Moonwalk

Part of the way through the year we discovered ambiguities in the referencing requirements, so coding work is on hold while we resolve that (which will show up in the release planning somehow). But we expect to deliver a working tool this year.

JSON Schema Implementation

The OASComply work includes parsing both standard (but extended) JSON Schema (for OAS 3.1) and the "superset-subset" custom JSON Schema variation found in OAS 3.0. As I worked with a JSON Schema implementation to extend its capabilities, the owner eventually recommended that I make an authorized fork as the work needed to fully support OAS + JSON Schema is pretty extensive. I'll post more about this when I'm ready to release the first public version of the fork.

It's looking like a busy 2024!

As you can see, I'm doing a lot of both specification and coding work this year. One downside of specification work is you're often focused on things that won't reach your average end-user for 5+ years. I am hopeful we'll settle on an OpenAPI release approach that gets new features into the hands of end-users very quickly. I'm looking forward to writing more about that process as well as my tool development work in the very near future!

Did you find this article valuable?

Support Henry Andrews by becoming a sponsor. Any amount is appreciated!