Moonwalk is a Special Interest Group working on the next major version of the OpenAPI Specification.
The OpenAPI Specification describes HTTP-based APIs in a machine-readable format, and Moonwalk addresses the need to evolve this standard for modern API design patterns and tooling requirements. The effort is guided by six core principles: establishing semantic meaning for both human and AI consumers, identifying API operations by their signatures across HTTP mechanics, remaining neutral on design debates while describing all HTTP-based APIs, creating standardized interfaces to reduce complexity for tool authors, modularizing concerns like API shapes and deployment configuration, and enabling automated upgrades from version 3.x to 4.0.
Moonwalk is exploratory work on version 4.0 with no planned completion date, so teams should continue using the stable 3.x versions for production APIs. The project is structured around discussions for proposing ideas, Architectural Design Records for capturing consensus decisions, and weekly open calls for focused discussion. Contributors should start new ideas as discussions rather than issues, and ADRs should be submitted only after sufficient agreement has formed. The formal specification document will be written once enough decisions have been made through ADRs to structure a coherent document.
The project operates through open discussion and consensus-building rather than rapid iteration. Weekly meetings are open to all participants, and decisions are documented through ADRs that capture just enough detail to move forward without over-specifying. The contribution process emphasizes building agreement in discussions before formalizing decisions, with feedback on proposals focused on whether they accurately capture the decision and related concerns rather than reopening settled directions.
