Skip to content

Latest commit

 

History

History
37 lines (23 loc) · 3.05 KB

README.md

File metadata and controls

37 lines (23 loc) · 3.05 KB

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, with a goal of publishing by the end of 2024.

Principles

Moonwalk is being developed in accordance with the following principles, which you can read in more detail in the announcement blog 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. 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
  5. 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 2024, we are using the following documents and processes:

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.