Work in progress! Each section links to issues that are relevant to fill out the rest of this document.
We are currently working on defining and documenting our new processes. Information in this document is up-to-date. Older (and sometimes now inaccurate) documentation can be found in DEVELOPMENT.md, which will be removed when everything is updated and documented here.
This section serves as a quick guide while we work on the full updated documentation.
If in doubt about a policy, please ask on our Slack before opening a PR.
No changes, no matter how trivial, are ever made to the contents of published specifications. The only potential changes to those documents are updates to link URLs if and only if the targeted document is moved by a 3rd party. Other changes to link URLs are not allowed.
The first PR for a change should be against the oldest release line to which it applies. Changes can then be forward-ported as appropriate.
The current (31 July 2024) active releases are:
| Version | Branch | File | Notes |
|---|---|---|---|
| 3.0.4 | v3.0.4-dev |
versions/3.0.4.md |
Soon to be published |
| 3.1.1 | v3.1.1-dev |
versions/3.1.1.md |
Soon to be published |
| 3.2.0 | v3.2.0-dev |
versions/3.2.0.md |
Planned for late 2024 |
| 4.0.0 | OAI/sig-moonwalk | discussions only | TBD, some proposals to be backported and published in 3.2.0 |
Schemas are only changed after the specification is changed. Changes are made on the main branch, and should be made to the YAML version only. The JSON version will be generated automatically.
Contributions to this repository should follow the style guide as described in this section.
Markdown files in this project should follow the style enforced by the markdownlint tool,
as configured by the .markdownlint.json file in the root of the project.
The following additional rules should be followed but currently are not enforced by tooling:
- The first mention of a normative reference or an OAS-defined Object in a (sub)*section is a link, additional mentions are not
- OAS-defined Foo Bar Objects are written in this style, and are not monospaced
- "example" instead of "sample" - this spec is not about statistics
- Use "OpenAPI Object" instead of "root"
- Fixed fields are monospaced
- Field values are monospaced in JSON notation:
true,false,null,"header"(with double-quotes around string values), ... - A combination of fixed field name with example value uses JS notation:
in: "header", combining rules 5 and 6 - An exception to 5-7 is colloquial use, for example "values of type
arrayorobject" - "type" is not monospaced, so the monospaced values aren't enclosed in double quotes. - Use Oxford commas, avoid Shatner commas.
- Use
<span id="thing"></span>for link anchors. The<a name="thing"></a>format has been deprecated.
- JSON Schema keywords -> "keyword"
- OpenAPI fixed fields -> "field"
- property of a "plain" JSON object that is not an OpenAPI-defined Foo Object -> "property"
- "attribute" is only used in the XML context and means "XML attribute"
- Issue #3528: 3.x.y patch release approach
- Issue #3529: 3.x minor release approach
- Issue #3715: Define and document our schema publishing process
- Issue #3785: Style guide / release checklist for the specification
As an organisation, we're open to changes, and these can be proposed by anyone. The specification is very widely adopted, and there is an appropriately high bar for wide appeal and due scrutiny as a result. We do not accept changes lightly (but we will consider any that we can).
Small changes are welcome as pull requests.
Bigger changes require a more formal process.
-
Start a discussion of type "Enhancements". The discussion entry must include some use cases, your proposed solution and the alternatives you have considered. If there is engagement and support for the proposal over time, then it can be considered as a candidate to move to the next stage.
-
It really helps to see the proposed change in action. Start using it as a
x-*extension if that's appropriate, or try to bring other evidence of your proposed solution being adopted. -
If you are adding support for something from another specification (such as OAuth), please point to implementations of that specification so that we can understand how, and to what degree, it is being used.
-
If the suggested change has good support, you will be asked to create a formal proposal. Use the template in the proposals directory, copy it to a new file, and complete it. Once you the document is ready, open a pull request on the main branch.
-
The proposal will be more closely reviewed and commented on or amended until it is either rejected or accepted. At that point, the proposal is merged into the
mainbranch and a pull request is opened to add the feature to the appropriatedevversion of the specification.
Questions are welcome on the process at any time. Use the discussions feature or find us in Slack.
- Issue #3847: Document milestone usage in DEVELOPMENT.md
- Issue #3848: Define and add new process labels and document general label usage in DEVELOPMENT.md
- Issue #3582: TOB info needs to be updated
- Issue #3523: Define triage role criteria and process
- Issue #3524: Define the maintainer role criteria and process
The OpenAPI Initiative uses GitHub Projects to manage work outside of the specification development process. There are currently two active projects:
We are beginning (as of mid-2024) to use GitHub discussions for open-ended topics such as major enhancements.
As of mid-2024, we prefer to use issues for topics that have a clear associated action. However, many existing issues are more open-ended, as they predate GitHub's discussions features.
In an effort to keep the list of issues up to date and easier to navigate through, issues get closed automatically when they become inactive.
This process makes use of the following labels:
Needs author feedback: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. This label needs to be added manually by people doing triage/experts whenever they reply. It's removed automatically by the workflow.No recent activity: the issue hasn't received a reply from its author within the last 10 days sinceNeeds author feedbackwas added and will be closed within 28 days if the author doesn't follow up. This label is added/removed automatically by the workflow.Needs attention: The issue's author has replied since theNeeds author feedbacklabel was set and the triage team will reply as soon as possible. This label needs to be removed manually by people doing triage/experts whenever they reply. It's added automatically by the workflow.
An issue is opened every week, 7 days in advance, for the Technical Developer Community (TDC), it provides the information to connect the meeting, and serves as a placeholder to build the agenda for the meeting. Anyone is welcome to attend the meeting, or to add items to the agenda as long as they plan on attending to present the item. These issues are also automatically pinned for visibility and labeled with "Housekeeping".
Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically.