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 axel.nennker@telekom.de

• 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 ron@swagger.io

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

• Update versions/3.1.0.md

Co-Authored-By: Darrel darrmi@microsoft.com

• 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 darrmi@microsoft.com

• Fix plural anchor

Co-Authored-By: Mike Ralphson mike.ralphson@gmail.com

• Remove superfluous specification

Co-Authored-By: Phil Sturgeon me@philsturgeon.uk

Co-authored-by: Darrel darrmi@microsoft.com
Co-authored-by: Mike Ralphson mike.ralphson@gmail.com
Co-authored-by: Phil Sturgeon me@philsturgeon.uk

• 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 ron@swagger.io

• 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 mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

• 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 ron@swagger.io
Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• Ron's wording for Darrels feedback

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• ted updates

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

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

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• Updated text for OperationRef

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com
Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• Make ABNF for runtime expressions complete

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 ron@swagger.io
Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

• fix difference between yaml and json in Response Object Examples

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

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

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

• Update versions/3.1.0.md

Co-Authored-By: Darrel darrmi@microsoft.com
Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• Fixed typo

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• explicit 'forward slash'

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

• OpenAPI not Open API

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• backticks

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

Co-authored-by: Ron ron@swagger.io
Co-authored-by: Mike Ralphson mike.ralphson@gmail.com
Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• Update 3.1.0.md

fixed typo

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• Removed confusing comment

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 ron@swagger.io
Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

• 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 mike.ralphson@gmail.com

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

Signed-off-by: Mike Ralphson mike.ralphson@gmail.com

Co-authored-by: seiya r108338@yahoo.co.jp
Co-authored-by: Adam Leventhal ahl@transposit.com
Co-authored-by: Sebastián Ramírez tiangolo@gmail.com
Co-authored-by: Ron ron@swagger.io
Co-authored-by: Phil Sturgeon me@philsturgeon.uk
Co-authored-by: Patrice Krakow patrice.krakow@gmail.com
Co-authored-by: Ted Epstein ted.epstein@reprezen.com
Co-authored-by: Darrel Miller darrmi@microsoft.com
Co-authored-by: Carsten Brandt mail@cebe.cc
Co-authored-by: Henry Andrews andrews_henry@yahoo.com
Co-authored-by: Sergej sergej2705@users.noreply.github.com
Co-authored-by: nasa9084 nasa.9084.bassclarinet@gmail.com
Co-authored-by: Erik Wilde dret@users.noreply.github.com

• 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 ron@swagger.io

• 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 me@philsturgeon.uk

• 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 darrmi@microsoft.com

• 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 darrmi@microsoft.com

• [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 darrmi@microsoft.com

• 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 ether@cpan.org

• Update versions/3.1.0.md

Co-authored-by: Ben Hutton relequestual@gmail.com

• new approach

Co-authored-by: Phil Sturgeon me@philsturgeon.uk
Co-authored-by: Karen Etheridge ether@cpan.org
Co-authored-by: Ben Hutton relequestual@gmail.com

• 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 darrel.miller@microsoft.com

• 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 darrel.miller@microsoft.com

• 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 mike.ralphson@gmail.com
Co-authored-by: Roberto Polli robipolli@gmail.com
Co-authored-by: Axel Nennker axel.nennker@telekom.de
Co-authored-by: Phil Sturgeon me@philsturgeon.uk
Co-authored-by: Mike Kistler mkistler@us.ibm.com
Co-authored-by: Darrel darrmi@microsoft.com
Co-authored-by: Arhimenrius arhimenrius@gmail.com
Co-authored-by: Lorna Jane Mitchell lorna@lornajane.net
Co-authored-by: Henry Andrews andrews_henry@yahoo.com
Co-authored-by: Alan Crosswell alan@crosswell.us
Co-authored-by: Helen Kosova hkosova@users.noreply.github.com
Co-authored-by: seiya r108338@yahoo.co.jp
Co-authored-by: Adam Leventhal ahl@transposit.com
Co-authored-by: Sebastián Ramírez tiangolo@gmail.com
Co-authored-by: Patrice Krakow patrice.krakow@gmail.com
Co-authored-by: Ted Epstein ted.epstein@reprezen.com
Co-authored-by: Carsten Brandt mail@cebe.cc
Co-authored-by: Sergej sergej2705@users.noreply.github.com
Co-authored-by: nasa9084 nasa.9084.bassclarinet@gmail.com
Co-authored-by: Erik Wilde dret@users.noreply.github.com
Co-authored-by: Marsh Gardiner marsh.gardiner@gmail.com
Co-authored-by: Phil Sturgeon me@philsturgeon.com
Co-authored-by: Karen Etheridge ether@cpan.org
Co-authored-by: Ben Hutton relequestual@gmail.com
Co-authored-by: Sebastien Rosset serosset@cisco.com
Co-authored-by: Darrel Miller darrel.miller@microsoft.com
Co-authored-by: Vladimir Gorej vladimir.gorej@gmail.com
Co-authored-by: Helen Kosova helen.kosova@smartbear.com