OAI/sig-moonwalk

Welcome to the OpenAPI Moonwalk SIG!

The OpenAPI Moonwalk Special Interest Group (SIG) is working on the next major release of the OpenAPI Specification (OAS), version 4.0.

Principles

Moonwalk is being developed in accordance with the following principles, which you can read in more detail in our 2025 blog post (an update to the 2024 post):

1. Semantics: Semantics provide purpose, whether the consumer is a human or an AI.
2. Signatures: An API operation is identifiable by its signature, which can be based on any aspect of HTTP mechanics.
3. Inclusion: Moonwalk aspires to describe all HTTP-based APIs while remaining neutral regarding any specific design debate.
4. Foundational Interfaces: Reduce the complexity for tooling authors by establishing standardized interfaces for parsing API description documents and defining consistent methods for expressing API structural semantics.
5. Separation of Concerns: Modularization will keep the scope of Moonwalk manageable with loose coupling among concerns such as HTTP interfaces ("API shapes"), deployment configuration, and content schema formats.
6. Mechanical Upgrading: An automated upgrade process from 3.x to 4.0 will be developed as part of the Moonwalk effort.

Contributing

As of March 2025, we are using the following documents and processes:

• The Initial Moonwalk Proposals launched this effort, and continue to serve as the reference point for our discussions
• Discussions: All Moonwalk ideas should start as discussions
• Architectural Design Records (ADRs) as discussions produce consensus, decisions are recorded as ADRs
• Issues should only be used to track actionable work items
• Meeting Agendas focus the discussion in our weekly calls, which are open to all

Issues and formal documents

We are not yet at the point of writing a formal specification, so there are very few reasons to file issues at this stage.

We will begin writing a formal document once enough decisions have been made through ADRs that a coherent document can be structured.

Writing ADRs

Before writing an ADR to submit as a PR, please make sure that there is sufficient agreement to move ahead either in the discussion or by getting a decision in the weekly call.

A good ADR decides just enough of a topic to allow moving on to the next decision. As discussions tend to be rather sprawling, it might take several ADRs to resolve everything needed to close a discussion.

Feedback on ADR PRs should be about whether the ADR captures the decision and all related concerns from the discussion. Details will likely be refined in the PR process, but if the direction of the decision is still being challenged, it is best to close the PR (or declare the ADR "rejected" before merging) and return to the GitHub discussion to re-build consensus.