What is the OpenAPI Moonwalk initiative and what changes does OpenAPI 4.0 introduce?

What is the OpenAPI Moonwalk initiative and what changes does OpenAPI 4.0 introduce? #

OpenAPI Moonwalk is the codename for the next major version of the OpenAPI Specification — OpenAPI 4.0. Managed by the OpenAPI Initiative (OAI) and developed openly on GitHub, Moonwalk represents a fundamental rethinking of how HTTP APIs are described. Rather than an incremental update like 3.0 to 3.1, Moonwalk is a ground-up redesign intended to address the accumulated limitations of the current specification while preserving what makes OpenAPI valuable: a human- and machine-readable contract for RESTful APIs.

Why a New Major Version? #

OpenAPI 3.x has been enormously successful, but years of real-world use have exposed structural limitations:

The Path Item model is rigid. Paths are the primary organizational unit, but modern APIs don’t always map cleanly to URL paths — especially APIs with complex resource hierarchies, overlapping parameter patterns, or path-level shared concerns.
Reuse is cumbersome. The $ref mechanism and components object support reuse, but composing operations from shared fragments is awkward. Teams end up either duplicating definitions or building complex tooling workarounds.
No native workflow or sequence description. OpenAPI describes individual operations in isolation. The Arazzo Specification was added as a companion to fill this gap, but it remains external to the core specification.
The schema story has improved but the structural model hasn’t. OpenAPI 3.1 achieved full JSON Schema alignment for schemas, but the operation model itself — paths, parameters, request bodies, responses — has not been revisited with the same rigor.
Extension proliferation. Gaps in the specification have been patched with x- extensions, leading to a fragmented ecosystem where different tools understand different extension dialects.

Moonwalk is designed to solve these problems from first principles rather than through further incremental extension.

Core Design Principles of Moonwalk #

The Moonwalk working group has articulated several guiding principles for OpenAPI 4.0:

Simplicity and Learnability #

One of the most common criticisms of OpenAPI 3.x is that it has a steep learning curve. The Path Item Object, Operation Object, Parameter Object, Request Body Object, and Response Object form a deeply nested hierarchy that surprises newcomers. Moonwalk aims to flatten and simplify this model wherever possible.

Composability #

Moonwalk introduces a more composable model where operations, parameters, and response patterns can be defined once and assembled into API descriptions without duplication. This composability is designed to work natively with the specification rather than relying on tooling conventions.

Decoupling Structure from HTTP #

OpenAPI has historically been tightly coupled to HTTP path structure. Moonwalk explores a model where the logical API structure is described independently of how it maps to HTTP, allowing a single API description to be used across different transport bindings or URL conventions.

Better Support for Modern API Patterns #

Moonwalk is being designed with explicit consideration for patterns that are common in modern APIs but awkward to describe in 3.x:

Webhooks (addressed in 3.1 but with further improvements planned)
Batch operations
Long-running operations (async job patterns)
Server-sent events (SSE)
Multi-protocol APIs (same logical API over REST and WebSockets)

Key Structural Changes Under Consideration #

The `request` Model #

Moonwalk is experimenting with replacing the paths top-level map with a more flexible request description model. Instead of organizing operations under URL path templates, operations may be defined more abstractly and bound to HTTP paths separately. This would allow the same logical operation to be exposed at multiple paths or with different URL conventions without duplication.

Unified Parameter Model #

In OpenAPI 3.x, parameters can be defined at the path item level or the operation level, and they interact in sometimes confusing ways. Moonwalk aims to unify the parameter model so that parameter inheritance, override, and sharing work predictably.

Native Reuse Without `$ref` Complexity #

While $ref will remain supported (it is part of JSON Schema), Moonwalk is exploring higher-level reuse constructs that don’t require deep understanding of JSON Reference and JSON Pointer semantics to use effectively.

Improved Extensibility Model #

Rather than unstructured x- extensions, Moonwalk may introduce a typed extension system where extensions declare their schema, enabling validators and tooling to check extension correctness rather than ignoring them silently.

Relationship to Existing Specifications #

Moonwalk is designed to coexist with, and eventually supersede, OpenAPI 3.x. Key compatibility considerations:

OpenAPI 3.x documents will remain valid — existing tools and documents won’t break. Moonwalk targets new API descriptions going forward.
JSON Schema alignment is preserved — the full JSON Schema 2020-12 vocabulary adopted in OpenAPI 3.1 carries forward into Moonwalk.
Arazzo integration — the Arazzo Specification for workflow descriptions may be more tightly integrated or harmonized with Moonwalk’s operation model.
Overlay Specification — the OpenAPI Overlay Specification is expected to remain relevant as a customization mechanism for Moonwalk documents.

Current Status and Timeline #

As of 2026, Moonwalk is in active development. The working group publishes drafts and discussion issues publicly in the OAI Moonwalk GitHub repository. The specification is not yet stable, and significant design decisions remain open.

The community is encouraged to participate in shaping the specification by:

Reading and commenting on GitHub issues
Joining the OpenAPI Initiative Slack workspace
Attending OAI community meetings
Providing feedback on draft proposals through the formal OAI contribution process

What Should API Teams Do Now? #

For teams actively designing APIs today, the practical guidance is:

Continue using OpenAPI 3.1 for new API designs. It is the current stable specification with growing tool support.
Follow the Moonwalk repository to understand the direction of travel and begin aligning internal practices with Moonwalk’s design principles.
Invest in good schema design using JSON Schema 2020-12, which will carry forward into Moonwalk.
Avoid deep reliance on tool-specific x- extensions where possible, as Moonwalk may introduce standard replacements.
Participate in the community — Moonwalk’s design is shaped by real-world API practitioner feedback.

Conclusion #

OpenAPI Moonwalk represents the most ambitious evolution of the OpenAPI Specification since its inception. By rethinking the core operation model, improving composability and reuse, and addressing modern API patterns that the current specification handles awkwardly, Moonwalk aims to keep OpenAPI the definitive standard for HTTP API description for the next decade. Teams invested in OpenAPI should follow the Moonwalk repository closely as the specification matures toward a stable release.

Last updated on April 30, 2026.