OpenAPI v4 (aka Moonwalk) Proposal

published on 2023/06/01

The primary goal of this proposal for a major new version of OpenAPI is to make it more approachable in order. One way it does so is by eliminating complexity that exists in OpenAPI v3. In addition, it aims to:

  • Support APIs that have different responses based on query parameters, headers and request bodies.
  • Support a broader range of URL design patterns
  • Reduce nested structures to improve readability and editability
  • Improve reusability of request and response patterns

OpenAPI has become the defacto standard for API descriptions, and it benefits from a very wide range of tooling support. However, due to its historic opinions of how an HTTP API should be designed, there are some scenarios that v3 cannot support. On the one hand, some in the community are asking for increased descriptiveness to support more scenarios. Yet at the same time, other bemoan how OpenAPI has become too complex for hand authoring.


OpenAI has been