v3.1.0-rc1 Release (#2370)

[PhilYue]

• 3.1.0 prep

• Update README

• Allow specification extensions in discriminator object

• Note that specification extensions beginning x-oas- are reserved

• security; add mutualTLS securityScheme type

• 832 add info.summary (832 add info.summary OAI/OpenAPI-Specification#1779)

• Fix: Summary field in Info Object OAI/OpenAPI-Specification#832. Add info.summary.

• Fix: summary is shord, description is verbose.

Be consistent with other definitions of summary and description.

• fix OIDC url and OAuth2 requirements

Signed-off-by: Axel Nennker [email protected]

• Update Schema Object to proper JSON Schema

• update vocab and arbitrary props

• another go at arbitrary keywords

• feedback from @handrews

• Support style, explode, allowReserved encoding for multipart/form-data (Support style, explode, allowReserved encoding for multipart/form-data OAI/OpenAPI-Specification#2066)

• Extend style, explode, allowReserved in encoding to multipart-formdata (OpenAPI 3.0 does not support csv-serialized form-data arrays OAI/OpenAPI-Specification#2018)

• Update versions/3.1.0.md

Co-Authored-By: Ron [email protected]

• Replace details of multipart/form-data format with referce to RFC 7578

• Update versions/3.1.0.md

Co-Authored-By: Darrel [email protected]

• default should match json schema

• removed json schema keyworld list, its just all of em.

• redundant $ref reference

• Correct Styles Values for spaceDelimited and pipeDelimited, as based on Style Examples, they support objects.

• Add support for webhooks as a top-level element (Add support for webhooks as a top-level element OAI/OpenAPI-Specification#2103)

• Add webhooks as a top-level element to the spec

• Add the changes from Improved callback examples OAI/OpenAPI-Specification#2048 and signpost webhooks

• Add an example of webhooks

• Relocate and expand on webhooks section following feedback

• Better wording to describe expectations on API consumers

• Clearer wording for why the paths element is here

• Update language to make callbacks clearer

• Align the OAS 3.1 nullable language with the 3.0.3 (Align the OAS 3.1 nullable language with the 3.0.3 OAI/OpenAPI-Specification#2115)

This adapts the language from PR OAI#2046, with minimal wording tweaks
to account for type now being able to have multiple values (type arrays).

• allow, but discourage, requestBody for GET, HEAD, DELETE (allow, but discourage, requestBody for GET, HEAD, DELETE OAI/OpenAPI-Specification#2117)

• Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 OAI/OpenAPI-Specification#2107)

• Checkpoint of draft

• Fix typo.

Co-Authored-By: Darrel [email protected]

• Fix plural anchor

Co-Authored-By: Mike Ralphson [email protected]

• Remove superfluous specification

Co-Authored-By: Phil Sturgeon [email protected]

Co-authored-by: Darrel [email protected]
Co-authored-by: Mike Ralphson [email protected]
Co-authored-by: Phil Sturgeon [email protected]

• Fix table cell formatting containing nullable description (Fix table cell formatting containing nullable description OAI/OpenAPI-Specification#2152)

• Add SPDX identifier field to license object, fixes identifier field for License Objects OAI/OpenAPI-Specification#1599 (Add SPDX identifier field to license object, fixes #1599 OAI/OpenAPI-Specification#2105)

• Add information about objects to the description too

• Make paths object optional (Make paths object optional OAI/OpenAPI-Specification#1781)

• Make paths object optional

• Adding reusable Path Item Objects

Under components

• Adopt DM's suggested change to OpenAPI doc definition

• Cleanup use of specification and definition where we mean document

• multipartite>composite, define ACL

• Add ' | Reference Object' to callbacks/webhooks

Co-authored-by: Ron [email protected]

• Fwd port v3.0.3 dev to v3.1.0 dev (Fwd port v3.0.3 dev to v3.1.0 dev OAI/OpenAPI-Specification#2163)

• fix typo in Callback Object

Signed-off-by: Mike Ralphson [email protected]

• retain typo in v3.0.2; fix for v3.0.3 (Callbacks key definition - fixes #1856 OAI/OpenAPI-Specification#1899)

Signed-off-by: Mike Ralphson [email protected]

• Clarify empty Security Requirement Object usage and validity (Clarify empty Security Requirement Object usage and validity OAI/OpenAPI-Specification#1886)

• Clarify empty Security Requirement Object usage and validity

• Reorder sentences to make clearer.

• Remove wrong text.

• Removed unneeded text.

Co-authored-by: Ron [email protected]
Signed-off-by: Mike Ralphson [email protected]

• Ron's wording for Darrels feedback

Signed-off-by: Mike Ralphson [email protected]

• ted updates

Signed-off-by: Mike Ralphson [email protected]

• Replace 'application' by 'API' within the 'Info Object' definition. (Consistent use of the word 'API' within the 'Info Object' definition. OAI/OpenAPI-Specification#2004)

Signed-off-by: Mike Ralphson [email protected]

• Path Templating Clarification - proposed fix for Path Templating Clarification: Is a variable without a corresponding path parameter valid? OAI/OpenAPI-Specification#1830. (Path Templating Clarification - proposed fix for #1830.  OAI/OpenAPI-Specification#1831)

• Proposed fix for Path Templating Clarification: Is a variable without a corresponding path parameter valid? OAI/OpenAPI-Specification#1830. Each variable expression in a path must have a corresponding path parameter.

• Path Templating Clarification: Is a variable without a corresponding path parameter valid? OAI/OpenAPI-Specification#1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter.

• Update Path Templating Clarification: Is a variable without a corresponding path parameter valid? OAI/OpenAPI-Specification#1830 fix with suggestion from Darrel

@darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea.

Signed-off-by: Mike Ralphson [email protected]

• yaml.org supports https, but www.yaml.org is misconfigured

Signed-off-by: Mike Ralphson [email protected]

• Updated text for OperationRef

Signed-off-by: Mike Ralphson [email protected]

• fix a typo in the Security Filtering section (fix a typo in the Security Filtering section OAI/OpenAPI-Specification#1837)

• fix a typo in the Security Filtering section

• Security filtering slight reword

Co-authored-by: Mike Ralphson [email protected]
Signed-off-by: Mike Ralphson [email protected]

• Make ABNF for runtime expressions complete

Signed-off-by: Mike Ralphson [email protected]

• Explain unclear semantics of property $ref in Path Item Object (Explain unclear semantics of property $ref in Path Item Object OAI/OpenAPI-Specification#1964)

• Explain unclear semantics of property $ref in Path Item Object

Currently, as explained in OAI#1038 (comment) the description of $ref in Path Item Object is unclear about the semantics behing it. I took the explaination from issue OAI#1038 to make it more clear.

• Update versions/3.1.0.md

Co-authored-by: Ron [email protected]
Signed-off-by: Mike Ralphson [email protected]

• Clarify constraints on Security Scheme Object Scheme Property (Clarify constraints on Security Scheme Object Scheme Property OAI/OpenAPI-Specification#1880)

• Wording around scheme extensions

• Clarified that securitySchemeScheme is only a SHOULD be registered scheme

Signed-off-by: Mike Ralphson [email protected]

• fix difference between yaml and json in Response Object Examples

Signed-off-by: Mike Ralphson [email protected]

• Server Variable Object clarifications (Server Variable Object clarifications OAI/OpenAPI-Specification#1809)

• Server Variable Object clarifications

• Toned language down for proper semver versioning

Signed-off-by: Mike Ralphson [email protected]

• Fix formatting errors in example (Fix formatting errors in example OAI/OpenAPI-Specification#2132)

Signed-off-by: Mike Ralphson [email protected]

• Update 3.0.3 for release (Update 3.0.3 for release OAI/OpenAPI-Specification#2149)

• Update README.md for release

• Update release date for 3.0.3

Signed-off-by: Mike Ralphson [email protected]

• Update versions/3.1.0.md

Co-Authored-By: Darrel [email protected]
Signed-off-by: Mike Ralphson [email protected]

• Fixed typo

Signed-off-by: Mike Ralphson [email protected]

• explicit 'forward slash'

Signed-off-by: Mike Ralphson [email protected]

• fix style keyword is not supported inside Schema object OAI/OpenAPI-Specification#2053: style keyword is not supported inside Schema object

Signed-off-by: Mike Ralphson [email protected]

• OpenAPI not Open API

Signed-off-by: Mike Ralphson [email protected]

• backticks

Signed-off-by: Mike Ralphson [email protected]

• minor clarification for operationId usage in link objects (minor clarification for operationId usage in link objects OAI/OpenAPI-Specification#1733)

• minor clarification

it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit.

• use right terminology

Co-Authored-By: Mike Ralphson [email protected]

Co-authored-by: Ron [email protected]
Co-authored-by: Mike Ralphson [email protected]
Signed-off-by: Mike Ralphson [email protected]

• Update 3.1.0.md

fixed typo

Signed-off-by: Mike Ralphson [email protected]

• Removed confusing comment

Signed-off-by: Mike Ralphson [email protected]

• Clarify the spec to allow optional or unspecified OAuth scopes (Clarify the spec to allow optional or unspecified OAuth scopes OAI/OpenAPI-Specification#1888)

• Referencing issue Scopes Object should be optional? OAI/OpenAPI-Specification#513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all.

• Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed.

• For Scopes Object should be optional? OAI/OpenAPI-Specification#513, adjusting language and removing examples

For OAI#513, adjusting language and removing examples as suggested by @webron.

• removed unnecessary example header

Co-authored-by: Ron [email protected]
Signed-off-by: Mike Ralphson [email protected]

• The examples keyword is not supported inside schema (The examples keyword is not supported inside schema OAI/OpenAPI-Specification#2042)

• examples not supported inside schema

• figured it out

• a tiny little edit

Signed-off-by: Mike Ralphson [email protected]

• Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. ([Consistency] Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. OAI/OpenAPI-Specification#2006)

Signed-off-by: Mike Ralphson [email protected]

• Fix formatting errors in example (Fix formatting errors in example OAI/OpenAPI-Specification#2132)

Signed-off-by: Mike Ralphson [email protected]

Co-authored-by: seiya [email protected]
Co-authored-by: Adam Leventhal [email protected]
Co-authored-by: Sebastián Ramírez [email protected]
Co-authored-by: Ron [email protected]
Co-authored-by: Phil Sturgeon [email protected]
Co-authored-by: Patrice Krakow [email protected]
Co-authored-by: Ted Epstein [email protected]
Co-authored-by: Darrel Miller [email protected]
Co-authored-by: Carsten Brandt [email protected]
Co-authored-by: Henry Andrews [email protected]
Co-authored-by: Sergej [email protected]
Co-authored-by: nasa9084 [email protected]
Co-authored-by: Erik Wilde [email protected]

• security; widen use of scopes array to other securityScheme types (security; widen use of scopes array to other securityScheme types OAI/OpenAPI-Specification#1829)

Co-authored-by: Ron [email protected]

• Allow summary and description as $ref siblings (Allow summary and description as $ref siblings outside schema objects OAI/OpenAPI-Specification#2181)

• HTTP not REST (OpenAPI supports any type of plain HTTP API OAI/OpenAPI-Specification#1946)

Co-authored-by: Phil Sturgeon [email protected]

• Missing updates

While going over the changes for the release notes, found two issues:

• The TOC entry for Relative references in URIs was not modified to match the change in the spec.
• The Paths Object had an extra sentence that should have not been there (referencing sub-documents and overlays).

• Remove boolean compatibility for exclusive* (Remove boolean compatibility for exclusive* OAI/OpenAPI-Specification#2226)

This brings exclusiveMinimum, exclusiveMaximum, minimum, and
maximum, into full modern JSON Schema compatibility.

There are no edits directly mentioning minimum and maximum,
but removing the boolean form simplifies their processing
by making it context-independent.

• Update "format" and "content*" for new JSON Schema (Update "format" and "content*" for new JSON Schema OAI/OpenAPI-Specification#2200)

• Update "format" and "content*" for new JSON Schema

This removes OAS formats and examples that are now superfluous
as they are part of the 2019-09 JSON Schema draft.

Similarly it deprecates the "byte" and "binary" formats in favor
of JSON Schema's "contentEncoding" and "contentMediaType" keywords,
and updates various related exapmles and other guidance.

It also removes confusingly blank rows in the OAS format table.

• "format" is an annotation

• Fix broken table, type, in Encoding Object

Broke some things while updating for "content*"

• Fix format of format

Backticks, not double quotes.

• Remove unneeded detail on "format"

This was just duplicating info from the JSON Schema spec.

Co-authored-by: Darrel [email protected]

• Remove "byte" and "binary" formats altogether.

Instead of just deprecating. The "content*" keywords now
cover these use cases.

• Harmonize JSON Schema content* + Media Type Object

Includes harmonizing with the Encoding Object. In general,
OpenAPI objects set the media type, although there is a case
for contentMediaType with multipart/form-data. Otherwise,
contentEncoding replaces the now-removed custom formats.

A possibly controversial change is to indicate unencoded binary
data by omitting type (or omitting the schema altogether), as
binary data does not conform to JSON string requirements.

This could still be done with type: string if that is preferred.
It's going to be a bit weird either way.

I can add wording in the next JSON Schema draft to clarify
whichever approach makes more sense.

• Fix typos from review

• Remove stray {}

• Fix inconsistencies contentMediaType and Encoding Object

Co-authored-by: Darrel [email protected]

• [3.1.0-dev] drop OAS semver requirement ([3.1.0-dev] drop OAS semver requirement OAI/OpenAPI-Specification#2243)

• drop OAS semver requirement

• Update versions/3.1.0.md

Co-authored-by: Darrel [email protected]

• Remove "nullable" entirely (Remove "nullable" entirely OAI/OpenAPI-Specification#2246)

• Update version for release (Update version for release OAI/OpenAPI-Specification#2269)

• $schema Guidance ($schema Guidance OAI/OpenAPI-Specification#2266)

• chore: explain how $schema might work

• reordered and made it specifically only schema resources

• Update versions/3.1.0.md

Co-authored-by: Karen Etheridge [email protected]

• Update versions/3.1.0.md

Co-authored-by: Ben Hutton [email protected]

• new approach

Co-authored-by: Phil Sturgeon [email protected]
Co-authored-by: Karen Etheridge [email protected]
Co-authored-by: Ben Hutton [email protected]

• v3.1.0: rephrase data-type section because format keyword can be used for any data type. (v3.1.0: rephrase data-type section because format keyword can be used for any data type. OAI/OpenAPI-Specification#2302)

• The JSON schema specification states the format keyword can be used for any data type, not just primitive types

• The JSON schema specification states the format keyword can be used for any data type, not just primitive types

• Added change to address Security filtering and templated paths - clarification needed OAI/OpenAPI-Specification#2287 (Empty path items OAI/OpenAPI-Specification#2328)

Co-authored-by: Darrel Miller [email protected]

• Make Server Variable Object's properties more strict (Make Server Variable Object's properties more strict OAI/OpenAPI-Specification#2335)

Followup to OAI#1809, now that we allow breaking changes.

• docs(Components): fix typo in schemas field type (docs(Components): fix typo in schemas field type OAI/OpenAPI-Specification#2337)

• Fix indentation of a YAML comment

• Removed required constraint on responses object (Removed required constraint on responses object OAI/OpenAPI-Specification#2329)

Co-authored-by: Darrel Miller [email protected]

• 3.1.0-rc1 Release prep (3.1.0-rc1 Release prep OAI/OpenAPI-Specification#2369)

• Update 3.1.0.md

• Merge branch 'master' into v3.1.0-dev

Co-authored-by: Mike Ralphson [email protected]
Co-authored-by: Roberto Polli [email protected]
Co-authored-by: Axel Nennker [email protected]
Co-authored-by: Phil Sturgeon [email protected]
Co-authored-by: Mike Kistler [email protected]
Co-authored-by: Darrel [email protected]
Co-authored-by: Arhimenrius [email protected]
Co-authored-by: Lorna Jane Mitchell [email protected]
Co-authored-by: Henry Andrews [email protected]
Co-authored-by: Alan Crosswell [email protected]
Co-authored-by: Helen Kosova [email protected]
Co-authored-by: seiya [email protected]
Co-authored-by: Adam Leventhal [email protected]
Co-authored-by: Sebastián Ramírez [email protected]
Co-authored-by: Patrice Krakow [email protected]
Co-authored-by: Ted Epstein [email protected]
Co-authored-by: Carsten Brandt [email protected]
Co-authored-by: Sergej [email protected]
Co-authored-by: nasa9084 [email protected]
Co-authored-by: Erik Wilde [email protected]
Co-authored-by: Marsh Gardiner [email protected]
Co-authored-by: Phil Sturgeon [email protected]
Co-authored-by: Karen Etheridge [email protected]
Co-authored-by: Ben Hutton [email protected]
Co-authored-by: Sebastien Rosset [email protected]
Co-authored-by: Darrel Miller [email protected]
Co-authored-by: Vladimir Gorej [email protected]
Co-authored-by: Helen Kosova [email protected]