-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
OpenAPI 3.0 does not support csv-serialized form-data arrays #2018
Comments
Here is my high-level proposal for how to fix this issue. I think it is highly desirable to fix this in a point release of 3.0, so it must be done compatibly. And I think that means that
In light of this, I think we have to use new keywords to specify this behavior. For example, we could add two new keywords to the I'll be the first to admit that this is not a pretty solution, and I'd be happy for suggestions on better names than Feedback welcome! |
A little more context: An example of this issue is the
In OpenAPI 2.0, because no "collectionFormat" is specified, the default is to encode this as a csv string. When we updated our API docs to OpenAPI 3.0, this form parameter became a property in the "multipart/form-data" request body:
By the reasoning explained in the issue description, this property defaults to |
Based on the discussion in the 10/10 OpenAPI TSC meeting, there may be more flexibility in how we address this issue than I previously stated. So here's my "ideal" solution to this issue: Remove the sentence "This property SHALL be ignored if the request body media type is not I understand that these sentences were originally added because of concern for how
Removing those qualifying sentences will make it possible to define array properties in multipart/form-data request bodies as |
After the TSC meeting last week, @webron reached out to me on Slack regarding this issue. @webron believes (apologies if I captured this incorrectly) that the OAS 3.0.x spec does not specify how arrays should be serialized in multipart request bodies. In particular, the statements
in the description of
Further, the encoding object is intended to be consistent with the way parameters are defined, using either a
Note that a query parameter for passing an array of strings can be defined as:
but when defined this way there is no way to specify how the array is serialized. So array parameters defined with a @webron believes that a proper fix would address both these problems in a consistent way. |
Not sure how to engage others in this discussion, so I guess I will just continue my monologue. I want to point out that the I failed to mention in my previous post that @webron believes that for an array property, I contend that @webron’s interpretation is inconsistent with the way the default values are described:
Further, if we adopted @webron’s interpretation, I don’t know this would work in practice. Consider a request body containing an array whose individual items are of contentType So I believe our clarification should be that And if we make that clarification, they why not allow the |
@mkistler I'm kind of parachuting into the middle here, but isn't part of the point of |
@handrews Thank you for joining the discussion!! Agreed that a key feature of In OpenAPI 2.0, the default behavior was to concatenate array items into a csv, all in one form part. In OpenAPI 3.0, the behavior is either unspecified, if you accept @webron's interpretation, or that each item is passed in a separate form part with no ability to specify csv concatenation into a single form part, using the interpretation I gave at the top of this issue. |
Following conversations in the TSC meeting, we are leaning towards allowing the style, explode and allowReserved properties in the encoding object to be used for multipart/form-data. multipart-form data is just a different serialization of url-encoded form and therefore should support the same set of behaviors. |
Closing as #2066 was merged! 🎉 |
* 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 (#1779) * Fix: #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 (#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (#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 (#2103) * Add webhooks as a top-level element to the spec * Add the changes from #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 (#2115) This adapts the language from PR #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 (#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (#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 (#2152) * Add SPDX identifier field to license object, fixes #1599 (#2105) * Add information about objects to the description too * Make paths object optional (#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 (#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 (#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Clarify empty Security Requirement Object usage and validity (#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. (#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Path Templating Clarification - proposed fix for #1830. (#1831) * 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. 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 (#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 (#1964) * 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.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 (#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 (#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 (#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (#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 #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 (#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 (#1888) * 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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (#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. (#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (#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 (#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (#2181) * HTTP not REST (#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* (#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 (#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 (#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (#2246) * Update version for release (#2269) 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>
* 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 (#1779) * Fix: #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 (#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (#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 (#2103) * Add webhooks as a top-level element to the spec * Add the changes from #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 (#2115) This adapts the language from PR #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 (#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (#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 (#2152) * Add SPDX identifier field to license object, fixes #1599 (#2105) * Add information about objects to the description too * Make paths object optional (#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 (#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 (#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Clarify empty Security Requirement Object usage and validity (#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. (#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Path Templating Clarification - proposed fix for #1830. (#1831) * 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. 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 (#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 (#1964) * 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.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 (#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 (#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 (#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (#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 #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 (#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 (#1888) * 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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (#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. (#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (#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 (#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (#2181) * HTTP not REST (#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* (#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 (#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 (#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (#2246) * Update version for release (#2269) * $schema Guidance (#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. (#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 #2287 (#2328) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * Make Server Variable Object's properties more strict (#2335) Followup to #1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (#2329) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * 3.1.0-rc1 Release prep (#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>
* 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 (#1779) * Fix: #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 (#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (#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 (#2103) * Add webhooks as a top-level element to the spec * Add the changes from #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 (#2115) This adapts the language from PR #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 (#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (#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 (#2152) * Add SPDX identifier field to license object, fixes #1599 (#2105) * Add information about objects to the description too * Make paths object optional (#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 (#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 (#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Clarify empty Security Requirement Object usage and validity (#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. (#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Path Templating Clarification - proposed fix for #1830. (#1831) * 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. 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 (#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 (#1964) * 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.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 (#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 (#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 (#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (#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 #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 (#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 (#1888) * 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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (#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. (#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (#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 (#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (#2181) * HTTP not REST (#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* (#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 (#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 (#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (#2246) * x-oas- to x-oai- (v3.1.0-dev) * Update version for release (#2269) * $schema Guidance (#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> * x-oai- / x-oas-; reserve both * v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (#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 #2287 (#2328) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * Make Server Variable Object's properties more strict (#2335) Followup to #1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (#2329) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * 3.1.0-rc1 Release prep (#2369) * Update 3.1.0.md * Merge branch 'master' into v3.1.0-dev * Added words relating to adopting semantics of JSON Schema (#2330) * Added words relating to adopting semantics of JSON Schema * Update versions/3.1.0.md Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * Update versions/3.1.0.md Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * fix typo in release history table * fix link to style values in serialization table * Fix misspelling of a keyword in text (#2389) * Update wording that referred to the year 2019 as the current year (#2390) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema (#2394) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema * Update verbiage to be more accurate Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.1.0.md (#2405) Improve wording about 'summary' and 'description' in Reference Object * long descriptions are cool too (#2408) Co-authored-by: Phil Sturgeon <me@philsturgeon.uk> * Unescaped Slashes Aint Welcome Around 'Ere (#2218) * oas 3.0 doesn't mention slashes not allowed * none of those either Co-authored-by: Phil Sturgeon <me@philsturgeon.uk> * Add missing field and use same summaries in Request Body Examples. (#2362) * Add missing schema type in Operation Object YAML Example. (#2361) * OAS schema dialect clarifications (#2399) * OAS schema dialect clarifications * OAS schema dialect clarifications Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * $schema is allowed in subschemas when bundling Co-authored-by: Ben Hutton <relequestual@gmail.com> * Schema dialect clarifications from Ben Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Use top-level jsonSchemaDialect field Co-authored-by: Ben Hutton <relequestual@gmail.com> * Update JSON Schema Draft to 2020-12 and make $ref resolution rules explicit (#2437) * fix http link to json-schema.org Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * fix http link to spec.commonmark.org Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Specify rules for $ref resolution Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Specify relative resolution rules for pathItem $ref and example externalValue Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update JSON Schema draft links to 2020-12 IETF pages Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make language about 'MUST be in the form of a ...' consistent Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make it clear pathItem $refs don't need to be external now Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make RFC links consistent with regard to spacing Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Allow a URI for example.externalValue fields This makes it fall under the rules for relative references. Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Explicitly call out $ref as a Relative Reference * Remove wording about what implementations SHOULD/MAY do with a $ref * Prefer 'referenced document' to 'referrant document' for clarity * Fix JSON Schema $ref resolution fallback rule * Add links back to #relativeReferences definition * Split #relativeReferences definition into URL and URI sections Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Clean-up wording about $refs in responsesObjects, fixes #1679 (#2442) * Clean-up wording about $refs in responsesObjects, fixes #1679 * Agreed to remove explicit verbiage around $refs in responseObjects, fixes #1679 * fix: two typos in versions/3.1.0.md (#2452) * Fix, clarify, and simplify content type schemas (#2351) * Fix, clarify, and simplify content type schemas This fixes #2349, which caught that an encoded PNG image is encoded into a text media type. In the process I realized some other errors, and simplified things. * HTTP `Content-Type` is always handled by OAS * Media Type Object key in most cases * Encoding object (possibly inferred from schema) in `multipart/form-data` * HTTP-level `Content-Encoding` is always handled by the OAS Header Object * JSON Schema "content*" is used for embedding one media type into another * the encoded resource is of media type `text/plain` * `"contentMediaType"` is the embedded media type after decoding * `"contentEncoding"` is how to encode/decode binary to/from text This removes any chance of `"contentMediaType"` conflicting with the Media Type Object key or with `contentType` in the Encoding Object, as they now always do different things. Likewise, the HTTP `Content-Encoding` header (with values like gzip, deflate, etc.) does different things than `"contentEncoding"` (which has values like base64, base64url, quoted-printable, etc.). The deprecated part header `Content-Transfer-Encoding` is likewise handled in the Encoding Object, but is probably never used. * Fix Content-Type to indicate semantics ...rather than literal content format on the wire. * Update 3.1.0.md Fixed a typo and changed a SHOULD to MAY. * Update versions/3.1.0.md * clarify default encoding content type value. * Describe interaction between JSON Schema contentEncoding and HTTP Content-Encoding header Co-authored-by: Mike Kistler <mkistler@us.ibm.com> Co-authored-by: Darrel <darrmi@microsoft.com> Co-authored-by: Mike Kistler <mkistler@us.ibm.com> * 3.1.0 release prep (#2461) * 3.1.0 release prep * Update README.md * reframing `user` as `author` (#2463) Per comment in review, authors determine whether a spec is a single or multipart document. Those who consume the spec care more about the information itself and less (or not at all directly) about how it was assembled. * fixed the dash character 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> Co-authored-by: Deven Phillips <InfoSec812@users.noreply.github.com> Co-authored-by: Vladimir <greatvovan@gmail.com> Co-authored-by: Quint Daenen <me@di-wu.be>
* 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 (OAI#1779) * Fix: OAI#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 (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#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 (OAI#2103) * Add webhooks as a top-level element to the spec * Add the changes from OAI#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 (OAI#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 (OAI#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (OAI#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 (OAI#2152) * Add SPDX identifier field to license object, fixes OAI#1599 (OAI#2105) * Add information about objects to the description too * Make paths object optional (OAI#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 (OAI#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 (OAI#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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 <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. (OAI#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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. 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 (OAI#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 (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.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 (OAI#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 (OAI#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 (OAI#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (OAI#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 OAI#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 (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 <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 (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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (OAI#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. (OAI#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (OAI#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 (OAI#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#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* (OAI#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 (OAI#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 (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (OAI#2246) * Update version for release (OAI#2269) 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>
* 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 (OAI#1779) * Fix: OAI#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 (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#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 (OAI#2103) * Add webhooks as a top-level element to the spec * Add the changes from OAI#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 (OAI#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 (OAI#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (OAI#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 (OAI#2152) * Add SPDX identifier field to license object, fixes OAI#1599 (OAI#2105) * Add information about objects to the description too * Make paths object optional (OAI#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 (OAI#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 (OAI#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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 <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. (OAI#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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. 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 (OAI#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 (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.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 (OAI#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 (OAI#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 (OAI#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (OAI#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 OAI#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 (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 <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 (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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (OAI#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. (OAI#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (OAI#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 (OAI#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#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* (OAI#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 (OAI#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 (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (OAI#2246) * Update version for release (OAI#2269) * $schema Guidance (OAI#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. (OAI#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 OAI#2287 (OAI#2328) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * Make Server Variable Object's properties more strict (OAI#2335) Followup to OAI#1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (OAI#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (OAI#2329) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * 3.1.0-rc1 Release prep (OAI#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>
* 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 (OAI#1779) * Fix: OAI#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 (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#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 (OAI#2103) * Add webhooks as a top-level element to the spec * Add the changes from OAI#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 (OAI#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 (OAI#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (OAI#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 (OAI#2152) * Add SPDX identifier field to license object, fixes OAI#1599 (OAI#2105) * Add information about objects to the description too * Make paths object optional (OAI#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 (OAI#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 (OAI#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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 <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. (OAI#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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. 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 (OAI#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 (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.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 (OAI#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 (OAI#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 (OAI#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (OAI#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 OAI#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 (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 <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 (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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (OAI#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. (OAI#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (OAI#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 (OAI#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#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* (OAI#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 (OAI#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 (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (OAI#2246) * x-oas- to x-oai- (v3.1.0-dev) * Update version for release (OAI#2269) * $schema Guidance (OAI#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> * x-oai- / x-oas-; reserve both * v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (OAI#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 OAI#2287 (OAI#2328) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * Make Server Variable Object's properties more strict (OAI#2335) Followup to OAI#1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (OAI#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (OAI#2329) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * 3.1.0-rc1 Release prep (OAI#2369) * Update 3.1.0.md * Merge branch 'master' into v3.1.0-dev * Added words relating to adopting semantics of JSON Schema (OAI#2330) * Added words relating to adopting semantics of JSON Schema * Update versions/3.1.0.md Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * Update versions/3.1.0.md Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * fix typo in release history table * fix link to style values in serialization table * Fix misspelling of a keyword in text (OAI#2389) * Update wording that referred to the year 2019 as the current year (OAI#2390) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema (OAI#2394) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema * Update verbiage to be more accurate Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.1.0.md (OAI#2405) Improve wording about 'summary' and 'description' in Reference Object * long descriptions are cool too (OAI#2408) Co-authored-by: Phil Sturgeon <me@philsturgeon.uk> * Unescaped Slashes Aint Welcome Around 'Ere (OAI#2218) * oas 3.0 doesn't mention slashes not allowed * none of those either Co-authored-by: Phil Sturgeon <me@philsturgeon.uk> * Add missing field and use same summaries in Request Body Examples. (OAI#2362) * Add missing schema type in Operation Object YAML Example. (OAI#2361) * OAS schema dialect clarifications (OAI#2399) * OAS schema dialect clarifications * OAS schema dialect clarifications Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * $schema is allowed in subschemas when bundling Co-authored-by: Ben Hutton <relequestual@gmail.com> * Schema dialect clarifications from Ben Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Use top-level jsonSchemaDialect field Co-authored-by: Ben Hutton <relequestual@gmail.com> * Update JSON Schema Draft to 2020-12 and make $ref resolution rules explicit (OAI#2437) * fix http link to json-schema.org Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * fix http link to spec.commonmark.org Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Specify rules for $ref resolution Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Specify relative resolution rules for pathItem $ref and example externalValue Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update JSON Schema draft links to 2020-12 IETF pages Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make language about 'MUST be in the form of a ...' consistent Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make it clear pathItem $refs don't need to be external now Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make RFC links consistent with regard to spacing Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Allow a URI for example.externalValue fields This makes it fall under the rules for relative references. Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Explicitly call out $ref as a Relative Reference * Remove wording about what implementations SHOULD/MAY do with a $ref * Prefer 'referenced document' to 'referrant document' for clarity * Fix JSON Schema $ref resolution fallback rule * Add links back to #relativeReferences definition * Split #relativeReferences definition into URL and URI sections Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Clean-up wording about $refs in responsesObjects, fixes OAI#1679 (OAI#2442) * Clean-up wording about $refs in responsesObjects, fixes OAI#1679 * Agreed to remove explicit verbiage around $refs in responseObjects, fixes OAI#1679 * fix: two typos in versions/3.1.0.md (OAI#2452) * Fix, clarify, and simplify content type schemas (OAI#2351) * Fix, clarify, and simplify content type schemas This fixes OAI#2349, which caught that an encoded PNG image is encoded into a text media type. In the process I realized some other errors, and simplified things. * HTTP `Content-Type` is always handled by OAS * Media Type Object key in most cases * Encoding object (possibly inferred from schema) in `multipart/form-data` * HTTP-level `Content-Encoding` is always handled by the OAS Header Object * JSON Schema "content*" is used for embedding one media type into another * the encoded resource is of media type `text/plain` * `"contentMediaType"` is the embedded media type after decoding * `"contentEncoding"` is how to encode/decode binary to/from text This removes any chance of `"contentMediaType"` conflicting with the Media Type Object key or with `contentType` in the Encoding Object, as they now always do different things. Likewise, the HTTP `Content-Encoding` header (with values like gzip, deflate, etc.) does different things than `"contentEncoding"` (which has values like base64, base64url, quoted-printable, etc.). The deprecated part header `Content-Transfer-Encoding` is likewise handled in the Encoding Object, but is probably never used. * Fix Content-Type to indicate semantics ...rather than literal content format on the wire. * Update 3.1.0.md Fixed a typo and changed a SHOULD to MAY. * Update versions/3.1.0.md * clarify default encoding content type value. * Describe interaction between JSON Schema contentEncoding and HTTP Content-Encoding header Co-authored-by: Mike Kistler <mkistler@us.ibm.com> Co-authored-by: Darrel <darrmi@microsoft.com> Co-authored-by: Mike Kistler <mkistler@us.ibm.com> * 3.1.0 release prep (OAI#2461) * 3.1.0 release prep * Update README.md * reframing `user` as `author` (OAI#2463) Per comment in review, authors determine whether a spec is a single or multipart document. Those who consume the spec care more about the information itself and less (or not at all directly) about how it was assembled. * fixed the dash character 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> Co-authored-by: Deven Phillips <InfoSec812@users.noreply.github.com> Co-authored-by: Vladimir <greatvovan@gmail.com> Co-authored-by: Quint Daenen <me@di-wu.be>
* 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 (OAI#1779) * Fix: OAI#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 (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#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 (OAI#2103) * Add webhooks as a top-level element to the spec * Add the changes from OAI#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 (OAI#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 (OAI#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (OAI#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 (OAI#2152) * Add SPDX identifier field to license object, fixes OAI#1599 (OAI#2105) * Add information about objects to the description too * Make paths object optional (OAI#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 (OAI#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 (OAI#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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 <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. (OAI#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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. 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 (OAI#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 (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.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 (OAI#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 (OAI#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 (OAI#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (OAI#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 OAI#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 (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 <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 (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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (OAI#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. (OAI#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (OAI#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 (OAI#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#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* (OAI#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 (OAI#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 (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (OAI#2246) * Update version for release (OAI#2269) 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>
* 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 (OAI#1779) * Fix: OAI#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 (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#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 (OAI#2103) * Add webhooks as a top-level element to the spec * Add the changes from OAI#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 (OAI#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 (OAI#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (OAI#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 (OAI#2152) * Add SPDX identifier field to license object, fixes OAI#1599 (OAI#2105) * Add information about objects to the description too * Make paths object optional (OAI#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 (OAI#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 (OAI#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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 <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. (OAI#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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. 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 (OAI#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 (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.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 (OAI#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 (OAI#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 (OAI#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (OAI#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 OAI#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 (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 <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 (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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (OAI#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. (OAI#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (OAI#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 (OAI#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#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* (OAI#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 (OAI#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 (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (OAI#2246) * Update version for release (OAI#2269) * $schema Guidance (OAI#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. (OAI#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 OAI#2287 (OAI#2328) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * Make Server Variable Object's properties more strict (OAI#2335) Followup to OAI#1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (OAI#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (OAI#2329) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * 3.1.0-rc1 Release prep (OAI#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>
* 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 (OAI#1779) * Fix: OAI#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 (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#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 (OAI#2103) * Add webhooks as a top-level element to the spec * Add the changes from OAI#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 (OAI#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 (OAI#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (OAI#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 (OAI#2152) * Add SPDX identifier field to license object, fixes OAI#1599 (OAI#2105) * Add information about objects to the description too * Make paths object optional (OAI#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 (OAI#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 (OAI#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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 <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. (OAI#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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. 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 (OAI#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 (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.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 (OAI#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 (OAI#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 (OAI#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (OAI#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 OAI#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 (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 <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 (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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (OAI#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. (OAI#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (OAI#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 (OAI#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#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* (OAI#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 (OAI#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 (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (OAI#2246) * x-oas- to x-oai- (v3.1.0-dev) * Update version for release (OAI#2269) * $schema Guidance (OAI#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> * x-oai- / x-oas-; reserve both * v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (OAI#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 OAI#2287 (OAI#2328) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * Make Server Variable Object's properties more strict (OAI#2335) Followup to OAI#1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (OAI#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (OAI#2329) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * 3.1.0-rc1 Release prep (OAI#2369) * Update 3.1.0.md * Merge branch 'master' into v3.1.0-dev * Added words relating to adopting semantics of JSON Schema (OAI#2330) * Added words relating to adopting semantics of JSON Schema * Update versions/3.1.0.md Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * Update versions/3.1.0.md Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * fix typo in release history table * fix link to style values in serialization table * Fix misspelling of a keyword in text (OAI#2389) * Update wording that referred to the year 2019 as the current year (OAI#2390) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema (OAI#2394) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema * Update verbiage to be more accurate Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.1.0.md (OAI#2405) Improve wording about 'summary' and 'description' in Reference Object * long descriptions are cool too (OAI#2408) Co-authored-by: Phil Sturgeon <me@philsturgeon.uk> * Unescaped Slashes Aint Welcome Around 'Ere (OAI#2218) * oas 3.0 doesn't mention slashes not allowed * none of those either Co-authored-by: Phil Sturgeon <me@philsturgeon.uk> * Add missing field and use same summaries in Request Body Examples. (OAI#2362) * Add missing schema type in Operation Object YAML Example. (OAI#2361) * OAS schema dialect clarifications (OAI#2399) * OAS schema dialect clarifications * OAS schema dialect clarifications Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * $schema is allowed in subschemas when bundling Co-authored-by: Ben Hutton <relequestual@gmail.com> * Schema dialect clarifications from Ben Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Use top-level jsonSchemaDialect field Co-authored-by: Ben Hutton <relequestual@gmail.com> * Update JSON Schema Draft to 2020-12 and make $ref resolution rules explicit (OAI#2437) * fix http link to json-schema.org Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * fix http link to spec.commonmark.org Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Specify rules for $ref resolution Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Specify relative resolution rules for pathItem $ref and example externalValue Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update JSON Schema draft links to 2020-12 IETF pages Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make language about 'MUST be in the form of a ...' consistent Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make it clear pathItem $refs don't need to be external now Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make RFC links consistent with regard to spacing Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Allow a URI for example.externalValue fields This makes it fall under the rules for relative references. Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Explicitly call out $ref as a Relative Reference * Remove wording about what implementations SHOULD/MAY do with a $ref * Prefer 'referenced document' to 'referrant document' for clarity * Fix JSON Schema $ref resolution fallback rule * Add links back to #relativeReferences definition * Split #relativeReferences definition into URL and URI sections Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Clean-up wording about $refs in responsesObjects, fixes OAI#1679 (OAI#2442) * Clean-up wording about $refs in responsesObjects, fixes OAI#1679 * Agreed to remove explicit verbiage around $refs in responseObjects, fixes OAI#1679 * fix: two typos in versions/3.1.0.md (OAI#2452) * Fix, clarify, and simplify content type schemas (OAI#2351) * Fix, clarify, and simplify content type schemas This fixes OAI#2349, which caught that an encoded PNG image is encoded into a text media type. In the process I realized some other errors, and simplified things. * HTTP `Content-Type` is always handled by OAS * Media Type Object key in most cases * Encoding object (possibly inferred from schema) in `multipart/form-data` * HTTP-level `Content-Encoding` is always handled by the OAS Header Object * JSON Schema "content*" is used for embedding one media type into another * the encoded resource is of media type `text/plain` * `"contentMediaType"` is the embedded media type after decoding * `"contentEncoding"` is how to encode/decode binary to/from text This removes any chance of `"contentMediaType"` conflicting with the Media Type Object key or with `contentType` in the Encoding Object, as they now always do different things. Likewise, the HTTP `Content-Encoding` header (with values like gzip, deflate, etc.) does different things than `"contentEncoding"` (which has values like base64, base64url, quoted-printable, etc.). The deprecated part header `Content-Transfer-Encoding` is likewise handled in the Encoding Object, but is probably never used. * Fix Content-Type to indicate semantics ...rather than literal content format on the wire. * Update 3.1.0.md Fixed a typo and changed a SHOULD to MAY. * Update versions/3.1.0.md * clarify default encoding content type value. * Describe interaction between JSON Schema contentEncoding and HTTP Content-Encoding header Co-authored-by: Mike Kistler <mkistler@us.ibm.com> Co-authored-by: Darrel <darrmi@microsoft.com> Co-authored-by: Mike Kistler <mkistler@us.ibm.com> * 3.1.0 release prep (OAI#2461) * 3.1.0 release prep * Update README.md * reframing `user` as `author` (OAI#2463) Per comment in review, authors determine whether a spec is a single or multipart document. Those who consume the spec care more about the information itself and less (or not at all directly) about how it was assembled. * fixed the dash character 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> Co-authored-by: Deven Phillips <InfoSec812@users.noreply.github.com> Co-authored-by: Vladimir <greatvovan@gmail.com> Co-authored-by: Quint Daenen <me@di-wu.be>
* 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 (OAI#1779) * Fix: OAI#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 (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#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 (OAI#2103) * Add webhooks as a top-level element to the spec * Add the changes from OAI#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 (OAI#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 (OAI#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (OAI#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 (OAI#2152) * Add SPDX identifier field to license object, fixes OAI#1599 (OAI#2105) * Add information about objects to the description too * Make paths object optional (OAI#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 (OAI#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 (OAI#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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 <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. (OAI#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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. 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 (OAI#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 (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.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 (OAI#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 (OAI#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 (OAI#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (OAI#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 OAI#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 (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 <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 (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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (OAI#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. (OAI#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (OAI#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 (OAI#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#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* (OAI#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 (OAI#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 (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (OAI#2246) * Update version for release (OAI#2269) 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>
* 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 (OAI#1779) * Fix: OAI#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 (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#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 (OAI#2103) * Add webhooks as a top-level element to the spec * Add the changes from OAI#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 (OAI#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 (OAI#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (OAI#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 (OAI#2152) * Add SPDX identifier field to license object, fixes OAI#1599 (OAI#2105) * Add information about objects to the description too * Make paths object optional (OAI#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 (OAI#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 (OAI#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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 <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. (OAI#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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. 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 (OAI#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 (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.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 (OAI#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 (OAI#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 (OAI#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (OAI#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 OAI#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 (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 <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 (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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (OAI#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. (OAI#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (OAI#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 (OAI#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#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* (OAI#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 (OAI#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 (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (OAI#2246) * Update version for release (OAI#2269) * $schema Guidance (OAI#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. (OAI#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 OAI#2287 (OAI#2328) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * Make Server Variable Object's properties more strict (OAI#2335) Followup to OAI#1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (OAI#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (OAI#2329) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * 3.1.0-rc1 Release prep (OAI#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>
* 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 (OAI#1779) * Fix: OAI#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 (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#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 (OAI#2103) * Add webhooks as a top-level element to the spec * Add the changes from OAI#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 (OAI#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 (OAI#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (OAI#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 (OAI#2152) * Add SPDX identifier field to license object, fixes OAI#1599 (OAI#2105) * Add information about objects to the description too * Make paths object optional (OAI#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 (OAI#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 (OAI#1899) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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 <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. (OAI#2004) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * 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. 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 (OAI#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 (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.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 (OAI#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 (OAI#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 (OAI#2132) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.0.3 for release (OAI#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 OAI#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 (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 <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 (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 <ron@swagger.io> Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * The examples keyword is not supported inside schema (OAI#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. (OAI#2006) Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Fix formatting errors in example (OAI#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 (OAI#1829) Co-authored-by: Ron <ron@swagger.io> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#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* (OAI#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 (OAI#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 (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <darrmi@microsoft.com> * Remove "nullable" entirely (OAI#2246) * x-oas- to x-oai- (v3.1.0-dev) * Update version for release (OAI#2269) * $schema Guidance (OAI#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> * x-oai- / x-oas-; reserve both * v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (OAI#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 OAI#2287 (OAI#2328) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * Make Server Variable Object's properties more strict (OAI#2335) Followup to OAI#1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (OAI#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (OAI#2329) Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> * 3.1.0-rc1 Release prep (OAI#2369) * Update 3.1.0.md * Merge branch 'master' into v3.1.0-dev * Added words relating to adopting semantics of JSON Schema (OAI#2330) * Added words relating to adopting semantics of JSON Schema * Update versions/3.1.0.md Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * Update versions/3.1.0.md Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Darrel Miller <darrel.miller@microsoft.com> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * fix typo in release history table * fix link to style values in serialization table * Fix misspelling of a keyword in text (OAI#2389) * Update wording that referred to the year 2019 as the current year (OAI#2390) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema (OAI#2394) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema * Update verbiage to be more accurate Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> Co-authored-by: Mike Ralphson <mike.ralphson@gmail.com> * Update 3.1.0.md (OAI#2405) Improve wording about 'summary' and 'description' in Reference Object * long descriptions are cool too (OAI#2408) Co-authored-by: Phil Sturgeon <me@philsturgeon.uk> * Unescaped Slashes Aint Welcome Around 'Ere (OAI#2218) * oas 3.0 doesn't mention slashes not allowed * none of those either Co-authored-by: Phil Sturgeon <me@philsturgeon.uk> * Add missing field and use same summaries in Request Body Examples. (OAI#2362) * Add missing schema type in Operation Object YAML Example. (OAI#2361) * OAS schema dialect clarifications (OAI#2399) * OAS schema dialect clarifications * OAS schema dialect clarifications Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * $schema is allowed in subschemas when bundling Co-authored-by: Ben Hutton <relequestual@gmail.com> * Schema dialect clarifications from Ben Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Use top-level jsonSchemaDialect field Co-authored-by: Ben Hutton <relequestual@gmail.com> * Update JSON Schema Draft to 2020-12 and make $ref resolution rules explicit (OAI#2437) * fix http link to json-schema.org Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * fix http link to spec.commonmark.org Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Specify rules for $ref resolution Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Specify relative resolution rules for pathItem $ref and example externalValue Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Update JSON Schema draft links to 2020-12 IETF pages Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make language about 'MUST be in the form of a ...' consistent Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make it clear pathItem $refs don't need to be external now Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Make RFC links consistent with regard to spacing Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Allow a URI for example.externalValue fields This makes it fall under the rules for relative references. Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Explicitly call out $ref as a Relative Reference * Remove wording about what implementations SHOULD/MAY do with a $ref * Prefer 'referenced document' to 'referrant document' for clarity * Fix JSON Schema $ref resolution fallback rule * Add links back to #relativeReferences definition * Split #relativeReferences definition into URL and URI sections Signed-off-by: Mike Ralphson <mike.ralphson@gmail.com> * Clean-up wording about $refs in responsesObjects, fixes OAI#1679 (OAI#2442) * Clean-up wording about $refs in responsesObjects, fixes OAI#1679 * Agreed to remove explicit verbiage around $refs in responseObjects, fixes OAI#1679 * fix: two typos in versions/3.1.0.md (OAI#2452) * Fix, clarify, and simplify content type schemas (OAI#2351) * Fix, clarify, and simplify content type schemas This fixes OAI#2349, which caught that an encoded PNG image is encoded into a text media type. In the process I realized some other errors, and simplified things. * HTTP `Content-Type` is always handled by OAS * Media Type Object key in most cases * Encoding object (possibly inferred from schema) in `multipart/form-data` * HTTP-level `Content-Encoding` is always handled by the OAS Header Object * JSON Schema "content*" is used for embedding one media type into another * the encoded resource is of media type `text/plain` * `"contentMediaType"` is the embedded media type after decoding * `"contentEncoding"` is how to encode/decode binary to/from text This removes any chance of `"contentMediaType"` conflicting with the Media Type Object key or with `contentType` in the Encoding Object, as they now always do different things. Likewise, the HTTP `Content-Encoding` header (with values like gzip, deflate, etc.) does different things than `"contentEncoding"` (which has values like base64, base64url, quoted-printable, etc.). The deprecated part header `Content-Transfer-Encoding` is likewise handled in the Encoding Object, but is probably never used. * Fix Content-Type to indicate semantics ...rather than literal content format on the wire. * Update 3.1.0.md Fixed a typo and changed a SHOULD to MAY. * Update versions/3.1.0.md * clarify default encoding content type value. * Describe interaction between JSON Schema contentEncoding and HTTP Content-Encoding header Co-authored-by: Mike Kistler <mkistler@us.ibm.com> Co-authored-by: Darrel <darrmi@microsoft.com> Co-authored-by: Mike Kistler <mkistler@us.ibm.com> * 3.1.0 release prep (OAI#2461) * 3.1.0 release prep * Update README.md * reframing `user` as `author` (OAI#2463) Per comment in review, authors determine whether a spec is a single or multipart document. Those who consume the spec care more about the information itself and less (or not at all directly) about how it was assembled. * fixed the dash character 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> Co-authored-by: Deven Phillips <InfoSec812@users.noreply.github.com> Co-authored-by: Vladimir <greatvovan@gmail.com> Co-authored-by: Quint Daenen <me@di-wu.be>
The OpenAPI 2.0 behavior
In OpenAPI 2.0, a parameter defined as
in: form
withtype: array
defaulted tocollectionFormat: csv
— meaning that the values of the array should be joined into a comma-separated string and passed in a single form data element ref.The OpenAPI 3.0 behavior
In OpenAPI 3.0, the default for arrays in a request body appears to be the equivalent of
collectionFormat: multi
— pass each element of the array in its own form data element.This was hard to track down but here's my step-by-step reading of the spec:
Details -- feel free to skip
In OpenAPI 3.0, form parameters are now described as properties in a request body.
An encoding attribute can be used to specify the serialization of parts of multipart request bodies.
Within the encoding object is a
style
property whichSo when the media type is other than
application/x-www-form-urlencoded
, the serialization will be handled using the defaultstyle
for query parameters, which is 'form' ref.In Style Values,
style
ofform
means:So what is
explode
? Back to the encoding object:application/x-www-form-urlencoded
.style
isform
, the default value istrue
.So when media type is other than
application/x-www-form-urlencoded
, all properties of the request body are serialized asstyle: form, explode: true
-- the equivalent ofcollectionFormat: multi
in OpenAPI 2.0.Conclusion
So the default value changed. That's not great but would probably be acceptable in a new major release of the spec, except that there appears to be no way to specify the OpenAPI 2.0 default behavior (
collectionFormat: csv
) for properties inmultipart
request bodies in OpenAPI 3.0. Both thestyle
andexplode
properties inencoding
are explicitly restricted to media typeapplication/x-www-form-urlencoded
, so only the default serialization --style: form, explode: true
is possible.The text was updated successfully, but these errors were encountered: