v3.1.0-rc1 Release #2370
Merged
v3.1.0-rc1 Release #2370
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Note that specification extensions beginning x-oas- are reserved
Allow specification extensions in discriminator object
security; add new securityScheme type of mutualTLS
* Fix: #832. Add info.summary. * Fix: summary is shord, description is verbose. Be consistent with other definitions of summary and description.
Signed-off-by: Axel Nennker <[email protected]>
fix OIDC url and OAuth2 requirements
#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (#2018) * Update versions/3.1.0.md Co-Authored-By: Ron <[email protected]> * Replace details of multipart/form-data format with referce to RFC 7578 * Update versions/3.1.0.md Co-Authored-By: Darrel <[email protected]>
Update Schema Objects to JSON Schema Draft 2019-09
…on Style Examples, they support objects.
* 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
This adapts the language from PR #2046, with minimal wording tweaks to account for type now being able to have multiple values (type arrays).
…OAS 3.1 (#2107) * Checkpoint of draft * Fix typo. Co-Authored-By: Darrel <[email protected]> * Fix plural anchor Co-Authored-By: Mike Ralphson <[email protected]> * Remove superfluous specification Co-Authored-By: Phil Sturgeon <[email protected]> Co-authored-by: Darrel <[email protected]> Co-authored-by: Mike Ralphson <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]>
* Make paths object optional * Adding reusable Path Item Objects Under `components` * Adopt DM's suggested change to OpenAPI doc definition * Cleanup use of specification and definition where we mean document * multipartite>composite, define ACL * Add ' | Reference Object' to callbacks/webhooks Co-authored-by: Ron <[email protected]>
* fix typo in Callback Object Signed-off-by: Mike Ralphson <[email protected]> * retain typo in v3.0.2; fix for v3.0.3 (#1899) Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Ron's wording for Darrels feedback Signed-off-by: Mike Ralphson <[email protected]> * ted updates Signed-off-by: Mike Ralphson <[email protected]> * Replace 'application' by 'API' within the 'Info Object' definition. (#2004) Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * yaml.org supports https, but www.yaml.org is misconfigured Signed-off-by: Mike Ralphson <[email protected]> * Updated text for OperationRef Signed-off-by: Mike Ralphson <[email protected]> * fix a typo in the Security Filtering section (#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Make ABNF for runtime expressions complete Signed-off-by: Mike Ralphson <[email protected]> * Explain unclear semantics of property `$ref` in Path Item Object (#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 <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * fix difference between yaml and json in Response Object Examples Signed-off-by: Mike Ralphson <[email protected]> * Server Variable Object clarifications (#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning Signed-off-by: Mike Ralphson <[email protected]> * Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson <[email protected]> * Update 3.0.3 for release (#2149) * Update README.md for release * Update release date for 3.0.3 Signed-off-by: Mike Ralphson <[email protected]> * Update versions/3.1.0.md Co-Authored-By: Darrel <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Fixed typo Signed-off-by: Mike Ralphson <[email protected]> * explicit 'forward slash' Signed-off-by: Mike Ralphson <[email protected]> * fix #2053: `style` keyword is not supported inside Schema object Signed-off-by: Mike Ralphson <[email protected]> * OpenAPI not Open API Signed-off-by: Mike Ralphson <[email protected]> * backticks Signed-off-by: Mike Ralphson <[email protected]> * minor clarification for operationId usage in link objects (#1733) * minor clarification it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit. * use right terminology Co-Authored-By: Mike Ralphson <[email protected]> Co-authored-by: Ron <[email protected]> Co-authored-by: Mike Ralphson <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Update 3.1.0.md fixed typo Signed-off-by: Mike Ralphson <[email protected]> * Removed confusing comment Signed-off-by: Mike Ralphson <[email protected]> * Clarify the spec to allow optional or unspecified OAuth scopes (#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 <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (#2006) Signed-off-by: Mike Ralphson <[email protected]> * Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson <[email protected]> Co-authored-by: seiya <[email protected]> Co-authored-by: Adam Leventhal <[email protected]> Co-authored-by: Sebastián Ramírez <[email protected]> Co-authored-by: Ron <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Patrice Krakow <[email protected]> Co-authored-by: Ted Epstein <[email protected]> Co-authored-by: Darrel Miller <[email protected]> Co-authored-by: Carsten Brandt <[email protected]> Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Sergej <[email protected]> Co-authored-by: nasa9084 <[email protected]> Co-authored-by: Erik Wilde <[email protected]>
Correct Styles Values for spaceDelimited and pipeDelimited, as based …
Co-authored-by: Phil Sturgeon <[email protected]>
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).
Missing updates
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 This removes OAS formats and examples that are now superfluous as they are part of the 2019-09 JSON Schema draft. Similarly it deprecates the "byte" and "binary" formats in favor of JSON Schema's "contentEncoding" and "contentMediaType" keywords, and updates various related exapmles and other guidance. It also removes confusingly blank rows in the OAS format table. * "format" is an annotation * Fix broken table, type, in Encoding Object Broke some things while updating for "content*" * Fix format of `format` Backticks, not double quotes. * Remove unneeded detail on "format" This was just duplicating info from the JSON Schema spec. Co-authored-by: Darrel <[email protected]> * Remove "byte" and "binary" formats altogether. Instead of just deprecating. The "content*" keywords now cover these use cases. * Harmonize JSON Schema content* + Media Type Object Includes harmonizing with the Encoding Object. In general, OpenAPI objects set the media type, although there is a case for `contentMediaType` with multipart/form-data. Otherwise, `contentEncoding` replaces the now-removed custom formats. A possibly controversial change is to indicate unencoded binary data by omitting `type` (or omitting the schema altogether), as binary data does not conform to JSON string requirements. This could still be done with `type: string` if that is preferred. It's going to be a bit weird either way. I can add wording in the next JSON Schema draft to clarify whichever approach makes more sense. * Fix typos from review * Remove stray {} * Fix inconsistencies contentMediaType and Encoding Object Co-authored-by: Darrel <[email protected]>
* drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <[email protected]>
* chore: explain how $schema might work * reordered and made it specifically only schema resources * Update versions/3.1.0.md Co-authored-by: Karen Etheridge <[email protected]> * Update versions/3.1.0.md Co-authored-by: Ben Hutton <[email protected]> * new approach Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Karen Etheridge <[email protected]> Co-authored-by: Ben Hutton <[email protected]>
…ed 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
Co-authored-by: Darrel Miller <[email protected]>
Followup to #1809, now that we allow breaking changes.
Co-authored-by: Darrel Miller <[email protected]>
Fix indentation of a YAML comment
* Update 3.1.0.md * Merge branch 'master' into v3.1.0-dev
darrelmiller
approved these changes
Oct 9, 2020
adamaltman
reviewed
Oct 10, 2020
|
|
||
| `$schema` MAY be present in any Schema Object, and if present MUST be used to determine which dialect should be used when processing the schema. | ||
|
|
||
| When `$schema` is not present, the default the following dialect MUST be assumed: `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. |
There was a problem hiding this comment.
Is something supposed to exist at this URL "https://spec.openapis.org/oas/3.1/schema-object"? (I get a 404, and I expected a schema object.)
There was a problem hiding this comment.
I opened this issue: #2371 about this comment.
PhilYue
added a commit
to PhilYue/OpenAPI-Specification
that referenced
this pull request
Oct 28, 2020
v3.1.0-rc1 Release (OAI#2370)
philsturgeon
added a commit
to philsturgeon/OpenAPI-Specification
that referenced
this pull request
Feb 18, 2021
* 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 <[email protected]> * Update Schema Object to proper JSON Schema * update vocab and arbitrary props * another go at arbitrary keywords * feedback from @handrews * Support style, explode, allowReserved encoding for multipart/form-data (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#2018) * Update versions/3.1.0.md Co-Authored-By: Ron <[email protected]> * Replace details of multipart/form-data format with referce to RFC 7578 * Update versions/3.1.0.md Co-Authored-By: Darrel <[email protected]> * default should match json schema * removed json schema keyworld list, its just all of em. * redundant $ref reference * Correct Styles Values for spaceDelimited and pipeDelimited, as based on Style Examples, they support objects. * Add support for webhooks as a top-level element (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 <[email protected]> * Fix plural anchor Co-Authored-By: Mike Ralphson <[email protected]> * Remove superfluous specification Co-Authored-By: Phil Sturgeon <[email protected]> Co-authored-by: Darrel <[email protected]> Co-authored-by: Mike Ralphson <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> * Fix table cell formatting containing `nullable` description (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 <[email protected]> * Fwd port v3.0.3 dev to v3.1.0 dev (OAI#2163) * fix typo in Callback Object Signed-off-by: Mike Ralphson <[email protected]> * retain typo in v3.0.2; fix for v3.0.3 (OAI#1899) Signed-off-by: Mike Ralphson <[email protected]> * Clarify empty Security Requirement Object usage and validity (OAI#1886) * Clarify empty Security Requirement Object usage and validity * Reorder sentences to make clearer. * Remove wrong text. * Removed unneeded text. Co-authored-by: Ron <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Ron's wording for Darrels feedback Signed-off-by: Mike Ralphson <[email protected]> * ted updates Signed-off-by: Mike Ralphson <[email protected]> * Replace 'application' by 'API' within the 'Info Object' definition. (OAI#2004) Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * yaml.org supports https, but www.yaml.org is misconfigured Signed-off-by: Mike Ralphson <[email protected]> * Updated text for OperationRef Signed-off-by: Mike Ralphson <[email protected]> * fix a typo in the Security Filtering section (OAI#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Make ABNF for runtime expressions complete Signed-off-by: Mike Ralphson <[email protected]> * Explain unclear semantics of property `$ref` in Path Item Object (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 <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * fix difference between yaml and json in Response Object Examples Signed-off-by: Mike Ralphson <[email protected]> * Server Variable Object clarifications (OAI#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning Signed-off-by: Mike Ralphson <[email protected]> * Fix formatting errors in example (OAI#2132) Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * Update versions/3.1.0.md Co-Authored-By: Darrel <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Fixed typo Signed-off-by: Mike Ralphson <[email protected]> * explicit 'forward slash' Signed-off-by: Mike Ralphson <[email protected]> * fix OAI#2053: `style` keyword is not supported inside Schema object Signed-off-by: Mike Ralphson <[email protected]> * OpenAPI not Open API Signed-off-by: Mike Ralphson <[email protected]> * backticks Signed-off-by: Mike Ralphson <[email protected]> * minor clarification for operationId usage in link objects (OAI#1733) * minor clarification it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit. * use right terminology Co-Authored-By: Mike Ralphson <[email protected]> Co-authored-by: Ron <[email protected]> Co-authored-by: Mike Ralphson <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Update 3.1.0.md fixed typo Signed-off-by: Mike Ralphson <[email protected]> * Removed confusing comment Signed-off-by: Mike Ralphson <[email protected]> * Clarify the spec to allow optional or unspecified OAuth scopes (OAI#1888) * Referencing issue OAI#513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all. * Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed. * For OAI#513, adjusting language and removing examples For OAI#513, adjusting language and removing examples as suggested by @webron. * removed unnecessary example header Co-authored-by: Ron <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (OAI#2006) Signed-off-by: Mike Ralphson <[email protected]> * Fix formatting errors in example (OAI#2132) Signed-off-by: Mike Ralphson <[email protected]> Co-authored-by: seiya <[email protected]> Co-authored-by: Adam Leventhal <[email protected]> Co-authored-by: Sebastián Ramírez <[email protected]> Co-authored-by: Ron <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Patrice Krakow <[email protected]> Co-authored-by: Ted Epstein <[email protected]> Co-authored-by: Darrel Miller <[email protected]> Co-authored-by: Carsten Brandt <[email protected]> Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Sergej <[email protected]> Co-authored-by: nasa9084 <[email protected]> Co-authored-by: Erik Wilde <[email protected]> * security; widen use of scopes array to other securityScheme types (OAI#1829) Co-authored-by: Ron <[email protected]> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#1946) Co-authored-by: Phil Sturgeon <[email protected]> * Missing updates While going over the changes for the release notes, found two issues: - The TOC entry for `Relative references in URIs` was not modified to match the change in the spec. - The `Paths Object` had an extra sentence that should have not been there (referencing sub-documents and overlays). * Remove boolean compatibility for exclusive* (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 <[email protected]> * Remove "byte" and "binary" formats altogether. Instead of just deprecating. The "content*" keywords now cover these use cases. * Harmonize JSON Schema content* + Media Type Object Includes harmonizing with the Encoding Object. In general, OpenAPI objects set the media type, although there is a case for `contentMediaType` with multipart/form-data. Otherwise, `contentEncoding` replaces the now-removed custom formats. A possibly controversial change is to indicate unencoded binary data by omitting `type` (or omitting the schema altogether), as binary data does not conform to JSON string requirements. This could still be done with `type: string` if that is preferred. It's going to be a bit weird either way. I can add wording in the next JSON Schema draft to clarify whichever approach makes more sense. * Fix typos from review * Remove stray {} * Fix inconsistencies contentMediaType and Encoding Object Co-authored-by: Darrel <[email protected]> * [3.1.0-dev] drop OAS semver requirement (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <[email protected]> * 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 <[email protected]> * Update versions/3.1.0.md Co-authored-by: Ben Hutton <[email protected]> * new approach Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Karen Etheridge <[email protected]> Co-authored-by: Ben Hutton <[email protected]> * v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (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 <[email protected]> * 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 <[email protected]> * 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 <[email protected]> Co-authored-by: Roberto Polli <[email protected]> Co-authored-by: Axel Nennker <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Mike Kistler <[email protected]> Co-authored-by: Darrel <[email protected]> Co-authored-by: Arhimenrius <[email protected]> Co-authored-by: Lorna Jane Mitchell <[email protected]> Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Alan Crosswell <[email protected]> Co-authored-by: Helen Kosova <[email protected]> Co-authored-by: seiya <[email protected]> Co-authored-by: Adam Leventhal <[email protected]> Co-authored-by: Sebastián Ramírez <[email protected]> Co-authored-by: Patrice Krakow <[email protected]> Co-authored-by: Ted Epstein <[email protected]> Co-authored-by: Carsten Brandt <[email protected]> Co-authored-by: Sergej <[email protected]> Co-authored-by: nasa9084 <[email protected]> Co-authored-by: Erik Wilde <[email protected]> Co-authored-by: Marsh Gardiner <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Karen Etheridge <[email protected]> Co-authored-by: Ben Hutton <[email protected]> Co-authored-by: Sebastien Rosset <[email protected]> Co-authored-by: Darrel Miller <[email protected]> Co-authored-by: Vladimir Gorej <[email protected]> Co-authored-by: Helen Kosova <[email protected]>
JelisaCooper
reviewed
Apr 2, 2021
| @@ -19,9 +19,9 @@ This GitHub project is the starting point for OpenAPI. Here you will find the in | |||
|
|
|||
| The current version of the OpenAPI specification is [OpenAPI Specification 3.0.3](versions/3.0.3.md). | |||
charjr
pushed a commit
to charjr/OpenAPI-Specification
that referenced
this pull request
Apr 27, 2023
* 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 <[email protected]> * Update Schema Object to proper JSON Schema * update vocab and arbitrary props * another go at arbitrary keywords * feedback from @handrews * Support style, explode, allowReserved encoding for multipart/form-data (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#2018) * Update versions/3.1.0.md Co-Authored-By: Ron <[email protected]> * Replace details of multipart/form-data format with referce to RFC 7578 * Update versions/3.1.0.md Co-Authored-By: Darrel <[email protected]> * default should match json schema * removed json schema keyworld list, its just all of em. * redundant $ref reference * Correct Styles Values for spaceDelimited and pipeDelimited, as based on Style Examples, they support objects. * Add support for webhooks as a top-level element (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 <[email protected]> * Fix plural anchor Co-Authored-By: Mike Ralphson <[email protected]> * Remove superfluous specification Co-Authored-By: Phil Sturgeon <[email protected]> Co-authored-by: Darrel <[email protected]> Co-authored-by: Mike Ralphson <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> * Fix table cell formatting containing `nullable` description (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 <[email protected]> * Fwd port v3.0.3 dev to v3.1.0 dev (OAI#2163) * fix typo in Callback Object Signed-off-by: Mike Ralphson <[email protected]> * retain typo in v3.0.2; fix for v3.0.3 (OAI#1899) Signed-off-by: Mike Ralphson <[email protected]> * Clarify empty Security Requirement Object usage and validity (OAI#1886) * Clarify empty Security Requirement Object usage and validity * Reorder sentences to make clearer. * Remove wrong text. * Removed unneeded text. Co-authored-by: Ron <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Ron's wording for Darrels feedback Signed-off-by: Mike Ralphson <[email protected]> * ted updates Signed-off-by: Mike Ralphson <[email protected]> * Replace 'application' by 'API' within the 'Info Object' definition. (OAI#2004) Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * yaml.org supports https, but www.yaml.org is misconfigured Signed-off-by: Mike Ralphson <[email protected]> * Updated text for OperationRef Signed-off-by: Mike Ralphson <[email protected]> * fix a typo in the Security Filtering section (OAI#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Make ABNF for runtime expressions complete Signed-off-by: Mike Ralphson <[email protected]> * Explain unclear semantics of property `$ref` in Path Item Object (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 <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * fix difference between yaml and json in Response Object Examples Signed-off-by: Mike Ralphson <[email protected]> * Server Variable Object clarifications (OAI#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning Signed-off-by: Mike Ralphson <[email protected]> * Fix formatting errors in example (OAI#2132) Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * Update versions/3.1.0.md Co-Authored-By: Darrel <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Fixed typo Signed-off-by: Mike Ralphson <[email protected]> * explicit 'forward slash' Signed-off-by: Mike Ralphson <[email protected]> * fix OAI#2053: `style` keyword is not supported inside Schema object Signed-off-by: Mike Ralphson <[email protected]> * OpenAPI not Open API Signed-off-by: Mike Ralphson <[email protected]> * backticks Signed-off-by: Mike Ralphson <[email protected]> * minor clarification for operationId usage in link objects (OAI#1733) * minor clarification it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit. * use right terminology Co-Authored-By: Mike Ralphson <[email protected]> Co-authored-by: Ron <[email protected]> Co-authored-by: Mike Ralphson <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Update 3.1.0.md fixed typo Signed-off-by: Mike Ralphson <[email protected]> * Removed confusing comment Signed-off-by: Mike Ralphson <[email protected]> * Clarify the spec to allow optional or unspecified OAuth scopes (OAI#1888) * Referencing issue OAI#513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all. * Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed. * For OAI#513, adjusting language and removing examples For OAI#513, adjusting language and removing examples as suggested by @webron. * removed unnecessary example header Co-authored-by: Ron <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (OAI#2006) Signed-off-by: Mike Ralphson <[email protected]> * Fix formatting errors in example (OAI#2132) Signed-off-by: Mike Ralphson <[email protected]> Co-authored-by: seiya <[email protected]> Co-authored-by: Adam Leventhal <[email protected]> Co-authored-by: Sebastián Ramírez <[email protected]> Co-authored-by: Ron <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Patrice Krakow <[email protected]> Co-authored-by: Ted Epstein <[email protected]> Co-authored-by: Darrel Miller <[email protected]> Co-authored-by: Carsten Brandt <[email protected]> Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Sergej <[email protected]> Co-authored-by: nasa9084 <[email protected]> Co-authored-by: Erik Wilde <[email protected]> * security; widen use of scopes array to other securityScheme types (OAI#1829) Co-authored-by: Ron <[email protected]> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#1946) Co-authored-by: Phil Sturgeon <[email protected]> * Missing updates While going over the changes for the release notes, found two issues: - The TOC entry for `Relative references in URIs` was not modified to match the change in the spec. - The `Paths Object` had an extra sentence that should have not been there (referencing sub-documents and overlays). * Remove boolean compatibility for exclusive* (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 <[email protected]> * Remove "byte" and "binary" formats altogether. Instead of just deprecating. The "content*" keywords now cover these use cases. * Harmonize JSON Schema content* + Media Type Object Includes harmonizing with the Encoding Object. In general, OpenAPI objects set the media type, although there is a case for `contentMediaType` with multipart/form-data. Otherwise, `contentEncoding` replaces the now-removed custom formats. A possibly controversial change is to indicate unencoded binary data by omitting `type` (or omitting the schema altogether), as binary data does not conform to JSON string requirements. This could still be done with `type: string` if that is preferred. It's going to be a bit weird either way. I can add wording in the next JSON Schema draft to clarify whichever approach makes more sense. * Fix typos from review * Remove stray {} * Fix inconsistencies contentMediaType and Encoding Object Co-authored-by: Darrel <[email protected]> * [3.1.0-dev] drop OAS semver requirement (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <[email protected]> * 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 <[email protected]> * Update versions/3.1.0.md Co-authored-by: Ben Hutton <[email protected]> * new approach Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Karen Etheridge <[email protected]> Co-authored-by: Ben Hutton <[email protected]> * v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (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 <[email protected]> * 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 <[email protected]> * 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 <[email protected]> Co-authored-by: Roberto Polli <[email protected]> Co-authored-by: Axel Nennker <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Mike Kistler <[email protected]> Co-authored-by: Darrel <[email protected]> Co-authored-by: Arhimenrius <[email protected]> Co-authored-by: Lorna Jane Mitchell <[email protected]> Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Alan Crosswell <[email protected]> Co-authored-by: Helen Kosova <[email protected]> Co-authored-by: seiya <[email protected]> Co-authored-by: Adam Leventhal <[email protected]> Co-authored-by: Sebastián Ramírez <[email protected]> Co-authored-by: Patrice Krakow <[email protected]> Co-authored-by: Ted Epstein <[email protected]> Co-authored-by: Carsten Brandt <[email protected]> Co-authored-by: Sergej <[email protected]> Co-authored-by: nasa9084 <[email protected]> Co-authored-by: Erik Wilde <[email protected]> Co-authored-by: Marsh Gardiner <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Karen Etheridge <[email protected]> Co-authored-by: Ben Hutton <[email protected]> Co-authored-by: Sebastien Rosset <[email protected]> Co-authored-by: Darrel Miller <[email protected]> Co-authored-by: Vladimir Gorej <[email protected]> Co-authored-by: Helen Kosova <[email protected]>
charjr
pushed a commit
to charjr/OpenAPI-Specification
that referenced
this pull request
Apr 27, 2023
* 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 <[email protected]> * Update Schema Object to proper JSON Schema * update vocab and arbitrary props * another go at arbitrary keywords * feedback from @handrews * Support style, explode, allowReserved encoding for multipart/form-data (OAI#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (OAI#2018) * Update versions/3.1.0.md Co-Authored-By: Ron <[email protected]> * Replace details of multipart/form-data format with referce to RFC 7578 * Update versions/3.1.0.md Co-Authored-By: Darrel <[email protected]> * default should match json schema * removed json schema keyworld list, its just all of em. * redundant $ref reference * Correct Styles Values for spaceDelimited and pipeDelimited, as based on Style Examples, they support objects. * Add support for webhooks as a top-level element (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 <[email protected]> * Fix plural anchor Co-Authored-By: Mike Ralphson <[email protected]> * Remove superfluous specification Co-Authored-By: Phil Sturgeon <[email protected]> Co-authored-by: Darrel <[email protected]> Co-authored-by: Mike Ralphson <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> * Fix table cell formatting containing `nullable` description (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 <[email protected]> * Fwd port v3.0.3 dev to v3.1.0 dev (OAI#2163) * fix typo in Callback Object Signed-off-by: Mike Ralphson <[email protected]> * retain typo in v3.0.2; fix for v3.0.3 (OAI#1899) Signed-off-by: Mike Ralphson <[email protected]> * Clarify empty Security Requirement Object usage and validity (OAI#1886) * Clarify empty Security Requirement Object usage and validity * Reorder sentences to make clearer. * Remove wrong text. * Removed unneeded text. Co-authored-by: Ron <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Ron's wording for Darrels feedback Signed-off-by: Mike Ralphson <[email protected]> * ted updates Signed-off-by: Mike Ralphson <[email protected]> * Replace 'application' by 'API' within the 'Info Object' definition. (OAI#2004) Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * yaml.org supports https, but www.yaml.org is misconfigured Signed-off-by: Mike Ralphson <[email protected]> * Updated text for OperationRef Signed-off-by: Mike Ralphson <[email protected]> * fix a typo in the Security Filtering section (OAI#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Make ABNF for runtime expressions complete Signed-off-by: Mike Ralphson <[email protected]> * Explain unclear semantics of property `$ref` in Path Item Object (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 <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * fix difference between yaml and json in Response Object Examples Signed-off-by: Mike Ralphson <[email protected]> * Server Variable Object clarifications (OAI#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning Signed-off-by: Mike Ralphson <[email protected]> * Fix formatting errors in example (OAI#2132) Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * Update versions/3.1.0.md Co-Authored-By: Darrel <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Fixed typo Signed-off-by: Mike Ralphson <[email protected]> * explicit 'forward slash' Signed-off-by: Mike Ralphson <[email protected]> * fix OAI#2053: `style` keyword is not supported inside Schema object Signed-off-by: Mike Ralphson <[email protected]> * OpenAPI not Open API Signed-off-by: Mike Ralphson <[email protected]> * backticks Signed-off-by: Mike Ralphson <[email protected]> * minor clarification for operationId usage in link objects (OAI#1733) * minor clarification it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit. * use right terminology Co-Authored-By: Mike Ralphson <[email protected]> Co-authored-by: Ron <[email protected]> Co-authored-by: Mike Ralphson <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * Update 3.1.0.md fixed typo Signed-off-by: Mike Ralphson <[email protected]> * Removed confusing comment Signed-off-by: Mike Ralphson <[email protected]> * Clarify the spec to allow optional or unspecified OAuth scopes (OAI#1888) * Referencing issue OAI#513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all. * Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed. * For OAI#513, adjusting language and removing examples For OAI#513, adjusting language and removing examples as suggested by @webron. * removed unnecessary example header Co-authored-by: Ron <[email protected]> Signed-off-by: Mike Ralphson <[email protected]> * 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 <[email protected]> * Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (OAI#2006) Signed-off-by: Mike Ralphson <[email protected]> * Fix formatting errors in example (OAI#2132) Signed-off-by: Mike Ralphson <[email protected]> Co-authored-by: seiya <[email protected]> Co-authored-by: Adam Leventhal <[email protected]> Co-authored-by: Sebastián Ramírez <[email protected]> Co-authored-by: Ron <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Patrice Krakow <[email protected]> Co-authored-by: Ted Epstein <[email protected]> Co-authored-by: Darrel Miller <[email protected]> Co-authored-by: Carsten Brandt <[email protected]> Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Sergej <[email protected]> Co-authored-by: nasa9084 <[email protected]> Co-authored-by: Erik Wilde <[email protected]> * security; widen use of scopes array to other securityScheme types (OAI#1829) Co-authored-by: Ron <[email protected]> * Allow summary and description as $ref siblings (OAI#2181) * HTTP not REST (OAI#1946) Co-authored-by: Phil Sturgeon <[email protected]> * Missing updates While going over the changes for the release notes, found two issues: - The TOC entry for `Relative references in URIs` was not modified to match the change in the spec. - The `Paths Object` had an extra sentence that should have not been there (referencing sub-documents and overlays). * Remove boolean compatibility for exclusive* (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 <[email protected]> * Remove "byte" and "binary" formats altogether. Instead of just deprecating. The "content*" keywords now cover these use cases. * Harmonize JSON Schema content* + Media Type Object Includes harmonizing with the Encoding Object. In general, OpenAPI objects set the media type, although there is a case for `contentMediaType` with multipart/form-data. Otherwise, `contentEncoding` replaces the now-removed custom formats. A possibly controversial change is to indicate unencoded binary data by omitting `type` (or omitting the schema altogether), as binary data does not conform to JSON string requirements. This could still be done with `type: string` if that is preferred. It's going to be a bit weird either way. I can add wording in the next JSON Schema draft to clarify whichever approach makes more sense. * Fix typos from review * Remove stray {} * Fix inconsistencies contentMediaType and Encoding Object Co-authored-by: Darrel <[email protected]> * [3.1.0-dev] drop OAS semver requirement (OAI#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel <[email protected]> * 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 <[email protected]> * Update versions/3.1.0.md Co-authored-by: Ben Hutton <[email protected]> * new approach Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Karen Etheridge <[email protected]> Co-authored-by: Ben Hutton <[email protected]> * v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (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 <[email protected]> * 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 <[email protected]> * 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 <[email protected]> Co-authored-by: Roberto Polli <[email protected]> Co-authored-by: Axel Nennker <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Mike Kistler <[email protected]> Co-authored-by: Darrel <[email protected]> Co-authored-by: Arhimenrius <[email protected]> Co-authored-by: Lorna Jane Mitchell <[email protected]> Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Alan Crosswell <[email protected]> Co-authored-by: Helen Kosova <[email protected]> Co-authored-by: seiya <[email protected]> Co-authored-by: Adam Leventhal <[email protected]> Co-authored-by: Sebastián Ramírez <[email protected]> Co-authored-by: Patrice Krakow <[email protected]> Co-authored-by: Ted Epstein <[email protected]> Co-authored-by: Carsten Brandt <[email protected]> Co-authored-by: Sergej <[email protected]> Co-authored-by: nasa9084 <[email protected]> Co-authored-by: Erik Wilde <[email protected]> Co-authored-by: Marsh Gardiner <[email protected]> Co-authored-by: Phil Sturgeon <[email protected]> Co-authored-by: Karen Etheridge <[email protected]> Co-authored-by: Ben Hutton <[email protected]> Co-authored-by: Sebastien Rosset <[email protected]> Co-authored-by: Darrel Miller <[email protected]> Co-authored-by: Vladimir Gorej <[email protected]> Co-authored-by: Helen Kosova <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changelog
See 3.1.0-rc0 for previous changes in 3.1.0, including the explanation of why there are breaking changes.
Breaking changes
enumnow MUST not be empty (changed from SHOULD).defaultnow MUST exist in theenumvalues, if such values are defined (changed from SHOULD).responsesare no longer required to be defined under the Operation Object.Clarifications
$schemakeyword (implicitly and explicitly).