OAS v3.0.3 Release #2148

webron · 2020-02-20T21:48:26Z

As a patch release, the following changes were made to improve the specification in terms of readability and accuracy. None of these modifications change the behavior of the spec.

Clarified how Path Templating works.
Clarified the meaning of Semantic Versioning as it applies to the OpenAPI Specification (note, this is the openapi field, not the version field).
Changed some hyperlinks from http to https.
Clarified add the notion of optional security on operations.
Added an explanation that the Server Variable Object's enum should not be empty. This is not a breaking change but should be considered as guidance for a more explicit restriction in the next major version.
Clarified paths under the Paths Object should start with a forward slash.
Clarified Path Item Object's $ref behavior with sibling fields.
Fixed a few examples.
Clarified the map structure of callbacks under the Operation Object.
Clarified how path parameters are being matched.
Clarified example/examples value(s) in the Parameter Object.
Fixed example for pipeDelimited object value.
Fixed Callback Object description.
Clarified Link Object's operationDef's description.
Improved ABNF for Runtime Expressions.
Clarified valid regex for pattern under Schema Object.
Clarified the behavior of nullable under Schema Object.
Fixed names of OAuth2 flows in the description of Security Scheme Object.
Improved description of Security Filtering section.

Updated text for OperationRef

Removed confusing comment

Added supported Ecma edition (5.1) for regular expressions in the link text and used the formal name: [Ecma-262 Edition 5.1](https://www.ecma-international.org/ecma-262/5.1/). See also: #1687

fixed typo

fix typo in Callback Object

fix difference between yaml and json in Response Object Examples

Add maybe forgotten back quotes for v3.0.3

explicit 'forward slash' for v3.0.3

Fixed typo

json-schema.org, commonmark.org and yaml.org now support https

Make ABNF for runtime expressions complete

…2004)

Improved callback examples

Corrected pattern regex dialect link

allow, but discourage, requestBody for GET, HEAD, DELETE

OpenAPI not Open API (3.0.3)

…equestBody Revert "allow, but discourage, requestBody for GET, HEAD, DELETE"

* Wording around scheme extensions * Clarified that securitySchemeScheme is only a SHOULD be registered scheme

Clarified supported Ecma edition for regex

* Server Variable Object clarifications * Toned language down for proper semver versioning

@darrelmiller

* Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter. * #1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter. * Update #1830 fix with suggestion from Darrel @darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea.

@webron

* Referencing issue #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 #513, adjusting language and removing examples For #513, adjusting language and removing examples as suggested by @webron. * removed unnecessary example header Co-authored-by: Ron <[email protected]>

* 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]>

* fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson <[email protected]>

* 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]>

* Explain unclear semantics of property `$ref` in Path Item Object Currently, as explained in #1038 (comment) the description of `$ref` in [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#pathItemObject) is unclear about the semantics behing it. I took the explaination from issue #1038 to make it more clear. * Update versions/3.0.3.md Co-authored-by: Ron <[email protected]>

* Update README.md for release * Update release date for 3.0.3

@webron

* 3.0.3 prep * Update README.md * Update README.md * Removed confusing comment * Updated text for OperationRef * Clarified supported Ecma edition for regex Added supported Ecma edition (5.1) for regular expressions in the link text and used the formal name: [Ecma-262 Edition 5.1](https://www.ecma-international.org/ecma-262/5.1/). See also: OAI#1687 * Make ABNF for runtime expressions complete * json-schema.org and commonmark.org now support https * Update 3.0.2.md fixed typo * Update 3.0.2.md fixed typo * Fixed typo * Update 3.0.3.md fixed typo * Update 3.0.2.md fixed typo * explicit 'forward slash' * add back quotes * fix difference between yaml and json in Response Object Examples * fix typo in Callback Object * Update 3.0.2.md * yaml.org supports https, but www.yaml.org is misconfigured * allow, but discourage, requestBody for GET, HEAD, DELETE * spelling error * retain typo in v3.0.2; fix for v3.0.3 (OAI#1899) * Corrected pattern regex dialect link * TSC 2019-10-03 Feedback This sentance was meant to paraphrase semver for clarifty, but ended up suggesting a confusion situation where new things essentially cannot really happen. @webron has context on this. * Ron's wording for Darrels feedback * ted updates * backticks * Improved callback examples * fix OAI#2053: `style` keyword is not supported inside Schema object * Resolved undocumented nullable behavior (OAI#2046) * Resolved undocumented nullable behavior OpenAPI Schema Objects and JSON Schema have a few fundamental differences, and this clears up a bit of confusion about one of them. * Added ted updates from oct 31st TSC Co-Authored-By: Ted Epstein <[email protected]> * Update versions/3.0.3.md Co-Authored-By: Darrel <[email protected]> * Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (OAI#2006) * The examples keyword is not supported inside schema (OAI#2042) * examples not supported inside schema * figured it out * a tiny little edit * Replace 'application' by 'API' within the 'Info Object' definition. (OAI#2004) * OpenAPI not Open API * Revert "allow, but discourage, requestBody for GET, HEAD, DELETE" * Clarify constraints on Security Scheme Object Scheme Property (OAI#1880) * Wording around scheme extensions * Clarified that securitySchemeScheme is only a SHOULD be registered scheme * Fix formatting errors in example (OAI#2132) * Server Variable Object clarifications (OAI#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning * Path Templating Clarification - proposed fix for OAI#1830. (OAI#1831) * Proposed fix for OAI#1830. Each variable expression in a path must have a corresponding path parameter. * OAI#1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter. * Update OAI#1830 fix with suggestion from Darrel @darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea. * Clarify the spec to allow optional or unspecified OAuth scopes (OAI#1888) * Referencing issue OAI#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 OAI#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]> * Clarify empty Security Requirement Object usage and validity (OAI#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]> * fix a typo in the Security Filtering section (OAI#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson <[email protected]> * minor clarification for operationId usage in link objects (OAI#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]> * Explain unclear semantics of property `$ref` in Path Item Object (OAI#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](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#pathItemObject) is unclear about the semantics behing it. I took the explaination from issue OAI#1038 to make it more clear. * Update versions/3.0.3.md Co-authored-by: Ron <[email protected]> * Update 3.0.3 for release (OAI#2149) * Update README.md for release * Update release date for 3.0.3 Co-authored-by: Darrel <[email protected]> Co-authored-by: Mike Ralphson <[email protected]> Co-authored-by: Sergej <[email protected]> Co-authored-by: Seiya <[email protected]> Co-authored-by: Alan Crosswell <[email protected]> Co-authored-by: Rich Ellis <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: nasa9084 <[email protected]> Co-authored-by: Ted Epstein <[email protected]> Co-authored-by: Patrice Krakow <[email protected]> Co-authored-by: Marsh Gardiner <[email protected]> Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Sebastián Ramírez <[email protected]> Co-authored-by: Erik Wilde <[email protected]> Co-authored-by: Carsten Brandt <[email protected]>

Blessed4eva · 2022-08-20T06:17:35Z

Debug

webron and others added 30 commits October 8, 2018 11:06

3.0.3 prep

89202e1

Update README.md

248478b

Update README.md

1d695a3

Removed confusing comment

d73aecb

Updated text for OperationRef

cf39a97

Merge pull request #1713 from OAI/dm/1677

c33bd24

Updated text for OperationRef

Merge pull request #1712 from OAI/dm/1692

218a321

Removed confusing comment

Clarified supported Ecma edition for regex

dcc37e1

Added supported Ecma edition (5.1) for regular expressions in the link text and used the formal name: [Ecma-262 Edition 5.1](https://www.ecma-international.org/ecma-262/5.1/). See also: #1687

Make ABNF for runtime expressions complete

24185d7

json-schema.org and commonmark.org now support https

35d925f

Update 3.0.2.md

b168a10

fixed typo

Update 3.0.2.md

e4823c5

fixed typo

Fixed typo

7837eb4

Update 3.0.3.md

d5fd6f1

fixed typo

Update 3.0.2.md

6f9212a

fixed typo

explicit 'forward slash'

7beb156

add back quotes

1fdf9bb

fix difference between yaml and json in Response Object Examples

46b140b

fix typo in Callback Object

013ce5a

Update 3.0.2.md

3dfaa1e

Merge pull request #1807 from seiyab/fix-typo-in-callback-object

f0d22dc

fix typo in Callback Object

Merge pull request #1802 from seiyab/fix-response-object-example

7c29ae0

fix difference between yaml and json in Response Object Examples

Merge pull request #1795 from seiyab/add-back-quotes-v3.0.3

76f85e6

Add maybe forgotten back quotes for v3.0.3

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

1d24cc8

Merge branch 'v3.0.3-dev' into more-https

effb92b

Merge pull request #1793 from seiyab/explicit-slash-patch-for-v3.0.3

63ce2cf

explicit 'forward slash' for v3.0.3

Merge pull request #1785 from sergej2705/v3.0.3-dev

9cd19ea

Fixed typo

Merge pull request #1763 from MikeRalphson/more-https

f623831

json-schema.org, commonmark.org and yaml.org now support https

Merge pull request #1756 from MikeRalphson/abnf-fix

b0ecc00

Make ABNF for runtime expressions complete

allow, but discourage, requestBody for GET, HEAD, DELETE

a135c98

patricekrakow and others added 20 commits December 5, 2019 08:28

Replace 'application' by 'API' within the 'Info Object' definition. (#…

67975ba

…2004)

Merge pull request #2048 from philsturgeon/improved-callback-examples

104b349

Improved callback examples

Merge pull request #1987 from ricellis/1985-pattern-regex

678cff6

Corrected pattern regex dialect link

Merge pull request #1937 from n2ygk/issue-1801/GET_DELETE_requestBody

b7b8238

allow, but discourage, requestBody for GET, HEAD, DELETE

OpenAPI not Open API

9dd1c20

Merge pull request #2081 from philsturgeon/v3.0.3-dev

6f0b0b6

OpenAPI not Open API (3.0.3)

Revert "allow, but discourage, requestBody for GET, HEAD, DELETE"

0e84751

Merge pull request #2114 from OAI/revert-1937-issue-1801/GET_DELETE_r…

9e2207a

…equestBody Revert "allow, but discourage, requestBody for GET, HEAD, DELETE"

Merge branch 'v3.0.3-dev' into v3.0.3-dev

55ce94c

Clarify constraints on Security Scheme Object Scheme Property (#1880)

302aeed

* Wording around scheme extensions * Clarified that securitySchemeScheme is only a SHOULD be registered scheme

Fix formatting errors in example (#2132)

fcdf414

Merge pull request #1725 from dvh/v3.0.3-dev

662775f

Clarified supported Ecma edition for regex

Server Variable Object clarifications (#1809)

640e342

* Server Variable Object clarifications * Toned language down for proper semver versioning

Clarify empty Security Requirement Object usage and validity (#1886)

080e927

* 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]>

fix a typo in the Security Filtering section (#1837)

22f06e8

* fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson <[email protected]>

Update 3.0.3 for release (#2149)

6ca9777

* Update README.md for release * Update release date for 3.0.3

webron marked this pull request as ready for review February 21, 2020 00:44

webron closed this Feb 21, 2020

webron reopened this Feb 21, 2020

Merge branch 'master' into v3.0.3-dev

b6e5964

darrelmiller approved these changes Feb 21, 2020

View reviewed changes

webron merged commit b748a88 into master Feb 21, 2020

webron deleted the v3.0.3-dev branch April 23, 2020 16:16

snyk-bot mentioned this pull request Jun 4, 2022

[Snyk] Upgrade yargs from 12.0.5 to 17.5.0 goshippo/OpenAPI-Specification#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OAS v3.0.3 Release #2148

OAS v3.0.3 Release #2148

webron commented Feb 20, 2020 •

edited

Loading

Blessed4eva commented Aug 20, 2022

OAS v3.0.3 Release #2148

OAS v3.0.3 Release #2148

Conversation

webron commented Feb 20, 2020 • edited Loading

Blessed4eva commented Aug 20, 2022

webron commented Feb 20, 2020 •

edited

Loading