OAS 3.1 - The Smaller List of Actualities

[earth2marsh]

Much progress has been made since The Big List of Possibilities #1466 was created 18+ months ago! Now as we head toward an actual 3.1 release, it is time to collect together all of improvements that may not be backwards compatible. The following is a list of the issues in scope for 3.1, and they should be considered launch blockers until each related PR has been approved and merged into 3.1.0-dev.

Nb: this is not an exhaustive changelog for v3.1.0.

• Resolve the SemVer ambiguities in Paraphrasing SemVer Caused Confusion #2022
• Update Schema Objects to JSON Schema Draft 2019-09 Update Schema Objects to JSON Schema Draft 2019-09 #1977
• Mutual Auth Certificate Support [OpenAPI.Next Proposal] Add client certificate to authentication methods #1004
• "Scopes" on Security Requirements for schemes other than OAuth2 Scopes for jwt-based security scheme #1393 API Key authentication should allow scopes to be defined. #1366
• CSV-serialized form-data arrays OpenAPI 3.0 does not support csv-serialized form-data arrays #2018
• Rewording constraints on bodies in HEAD/DELETE PR allow, but discourage, requestBody for GET, HEAD, DELETE #1937 allow, but discourage, requestBody for GET, HEAD, DELETE #2117
• Clarify difference in behavior between $ref inside and outside of schema object Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 #2107
• Post-Update Schema Objects to JSON Schema Draft 2019-09 #1977 knock-on issues Remaining JSON Schema Tweaks for OAS 3.1 #2099

We anticipate at least one release candidate (RC) on the path to the actual release.

Known issues that could be included but might not make the 3.1 release:

• Overlays Yet another Overlay proposal Overlay-Specification#36

[handrews]

As a follow-on to #1977, there needs to be some decision over how $schema should be used in the context of OAS. See issue #2017 which uses PR #2016 (starting point for a schema for OAS 3.1) as an example.

[andig]

I‘m totally missing #93. It is 6 years old and has community demand. There isn‘t even any comment as to why this would not make it to the long or short list. It also seems to be a low-hanging fruit?

[MikeRalphson]

@andig the rationale is here #622 (comment)

[andig]

@andig the rationale is here #622 (comment)

I don‘t fully understand the reasoning of the response, but that‘s fine. Isn‘t it really „wont fix due to...“ then? I feel the message doesn‘t come quite across.

Forgive me for commenting here, your comment is highly appreciated.