From b2d8fa9a6e1dc44f7be775589fe0f7879f3b8484 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 15 Sep 2024 17:26:56 +0100 Subject: [PATCH 1/8] Add written-word drafts since a PR is a good way to review --- blog-post.md | 68 ++++++++++++++++++++++++++++++++++++++++++ release-notes-3.1.1.md | 53 ++++++++++++++++++++++++++++++++ 2 files changed, 121 insertions(+) create mode 100644 blog-post.md create mode 100644 release-notes-3.1.1.md diff --git a/blog-post.md b/blog-post.md new file mode 100644 index 0000000000..543a6aa70c --- /dev/null +++ b/blog-post.md @@ -0,0 +1,68 @@ +OpenAPI Initiative is pleased to announce a patch release of the 3.0 and 3.1 OpenAPI specifications. +In patch releases, no changes are made to the way that APIs are described, but the specification wording itself contains many updates, expansions, and clarifications where previous the points may have been unclear or not covered. +Think of this release as the "Words Mean Things" edition. + +## Released versions + +3.1.1 is the newest and recommended version of OpenAPI. +If you are starting a new project today, or have the option to upgrade, this is your target version. +Tooling that supports 3.1.0 is expected to work without problems on 3.1.1 since the patch releases don't contain structure changes. + +3.0.4 is an additional release on the 3.0 branch to incorporate the improved wording to the 3.0 branch of the specification where the changes applied there. +It is expected that 3.0.4 will be the final release in the 3.0.x line. + +## Summary of changes + +The releases include as many explanations, clarifications and expanded sections as we could manage, driven mostly by the questions and comments we get from the users and tools creators of OpenAPI. +The highlights include a lot of new content to expand on existing content and reduce ambiguity. +The sections regarding parameters, encoding and schemas have had significant updates and expansion to cover more cases. +You will also find some security clarifications and a whole new "Security Considerations" section has been added. + +Look out for additional apendices with some great additional explanations that support the additions to the main body of the specification. +We added a great collection of new content sections and appendix entries about handling data including data types, serialization and encoding. +In 3.1, there is more information about parsing documents and resolving references since the adoption of JSON Schema. + +The updates also strayed into distinctly "meta" areas, so we've also got: + +- examples of using the `example(s)` fields +- reference to a schema to represent the OpenAPI schema +- we have clearly defined when something was undefined + +## Beyond the specification + +In addition to the main specifications that you can always find at https://spec.openapis.org, there are a number of other resources that you may find helpful: + +- OpenAPI's documentation and examples is available at https://learn.openapis.org. + This site holds all the examples used in the main OpenAPI specification, and much more additional information besides. +- A [non-authoritative JSON Schema representation of the OpenAPI specification](https://spec.openapis.org/#non-normative-json-schemas) is available. + This representation should not require changes between 3.1.0 and 3.1.1 since patch releases don't change the structure. +- The [formats registry](https://spec.openapis.org/registry/format/index.html) and the [extensions registry](https://spec.openapis.org/registry/extension/index.html) list some common patterns in specification use. + +We also updated the tooling that publishes the specification, changed the GitHub repository structure, cleaned up and reformatted all the Markdown content, and improved our workflow automation. +Which doesn't affect the specification but does make it a nicer place to be and hopefully makes the next release easier too. + +## Upgrade process + +Most users and tool vendors should have no action to take, since the patch releases contain only wording changes or clarifications and no structure changes. +That said, especially if you publish OpenAPI tools, take a look at the release notes on GitHub to check that there are no surprises! + +## Acknowledgements + +So many contributors have contributed to this release, it's not possible to name them all. +If you suggested an idea, joined our regular calls to discuss the changes, opened or reviewed a pull request, or participated in any of the discussions about the changes, then we thank you! +We had a LOT of help, and the new releases are very much improved for it (also the previous release was quite some time ago, a lot of people added to the project in the meantime). + +Particular thanks goes to the Technical Steering Committee members who teamed up and shepherded the whole thing through, and to Henry Andrews whose counsel and hands-on help were a very welcome addition to the process. + +## Get involved + +There are lots of ways to get involved with OpenAPI, and we like to hear from everyone who uses OpenAPI (or wants to)! + +- Start with [the OpenAPI Initiative website](https://openapis.org) to find out more about all our activities. +- Your organization can [become an OpenAPI Initiative member](https://www.openapis.org/membership/join). +- All the standards and resources are developed in the open on GitHub. + Try one of these projects [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification), the new [Arazzo specification](https://github.com/OAI/Arazzo-Specification), the upcoming [Overlay specification](https://github.com/OAI/Overlay-Specification), or the [learn.openapis.org site](https://github.com/OAI/learn.openapis.org). + All the projects have open issues/discussions and welcome new contributors. +- Join one of our [regular open meetings](https://www.openapis.org/calendar) to find out what's coming up and to get involved. +- We have a Slack group that you can also [get an invitation to join](https://communityinviter.com/apps/open-api/openapi). + diff --git a/release-notes-3.1.1.md b/release-notes-3.1.1.md new file mode 100644 index 0000000000..85748bb87f --- /dev/null +++ b/release-notes-3.1.1.md @@ -0,0 +1,53 @@ +# Release Notes + +This release makes no changes to the OpenAPI standard, however the formal specification document had multiple improvements, including: +- clarity and expanded explanations including several new appendices with supplementary details +- examples and additional documentation moved to https://learn.openapis.org +- the HTML rendering of the specification at https://spec.openapis.org is now considered the authoritative version (formerly it was the Markdown source on GitHub) + +OpenAPI description writers should mark their OpenAPI descriptions with the version of OpenAPI specification they used to write their specification, updating where possible. + +Tool creators should also not expect changes, but it is recommended to check the list of changes below. + +## Clearer Definitions + +Introduce consistent language around OpenAPI Document/Description/Definition: +- OpenAPI Description means the OpenAPI description of an API, whether it is in one or many files. +- a document means a single file. +- an "entry document" is where the OpenAPI description for an API starts; it may reference other documents. + +Improved language regarding schemas, explaining the difference between the OpenAPI schema, the schemas used within the OpenAPI schema, and the use of a non-authoritative JSON Schema to supplement the written spec. + +[3.1.1]Added guidance around use of schema dialects. + +## References + +Additional guidance for resolving references and parsing documents was added. +Resolving component names, tags, and operationIds are clarified. +[3.1.1]The adoption of JSON Schema in 3.1.x changed the parsing and referencing, and a new section was added to cover the changes in more depth than in 3.1.0. + +[3.1.1]Improved explanation of URLs and URIs, and made clear which to use for each URL/URI field. +Clarified that Markdown links are resolved in relation to their rendered context. + +## Data Types + +Extensive clarifications on data types and encoding. +Added a section on handling binary data. + +## Security + +Added a note that the `security` array that is empty or missing values does not indicate that no security arrangements exist for this API. +Updated references to other standards where newer versions are available, and added more explanation for OpenIDConnect. +Added a "Security Concerns" section containing advice for implementers and users of OpenAPI. + +## Request Data + +The parameters section was extensively refactored. +Examples were updated, improved and explanations added. +Headers have their own section with examples and specific information. + +Explanation of OpenAPI `example` and `examples` was expanded and the "Working with Examples" section added with clearer description and examples included. + +Information regarding file uploads, form-urlencoded request bodies and multipart content were expanded and moved to the refactored Encoding Object section to provide better coverage of edge cases and more examples. + + From 7c3faf6f5c2c85084846bd4d49133bd5371038e4 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 17 Sep 2024 10:21:35 +0200 Subject: [PATCH 2/8] Apply suggestions from code review Co-authored-by: Darrel --- blog-post.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/blog-post.md b/blog-post.md index 543a6aa70c..f312e9f7fa 100644 --- a/blog-post.md +++ b/blog-post.md @@ -1,4 +1,4 @@ -OpenAPI Initiative is pleased to announce a patch release of the 3.0 and 3.1 OpenAPI specifications. +The OpenAPI Initiative is pleased to announce a patch release of the 3.0 and 3.1 OpenAPI specifications. In patch releases, no changes are made to the way that APIs are described, but the specification wording itself contains many updates, expansions, and clarifications where previous the points may have been unclear or not covered. Think of this release as the "Words Mean Things" edition. @@ -18,7 +18,7 @@ The highlights include a lot of new content to expand on existing content and re The sections regarding parameters, encoding and schemas have had significant updates and expansion to cover more cases. You will also find some security clarifications and a whole new "Security Considerations" section has been added. -Look out for additional apendices with some great additional explanations that support the additions to the main body of the specification. +Look out for additional appendices with some great explanations that support the additions to the main body of the specification. We added a great collection of new content sections and appendix entries about handling data including data types, serialization and encoding. In 3.1, there is more information about parsing documents and resolving references since the adoption of JSON Schema. @@ -26,7 +26,7 @@ The updates also strayed into distinctly "meta" areas, so we've also got: - examples of using the `example(s)` fields - reference to a schema to represent the OpenAPI schema -- we have clearly defined when something was undefined +- we have clearly defined when something was undefined or implementation dependent ## Beyond the specification From 31bae9b97f3c9fa30feb872fbe610f0d717b4b24 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 17 Sep 2024 10:24:47 +0200 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Marsh Gardiner --- release-notes-3.1.1.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/release-notes-3.1.1.md b/release-notes-3.1.1.md index 85748bb87f..9a2d92fe12 100644 --- a/release-notes-3.1.1.md +++ b/release-notes-3.1.1.md @@ -1,20 +1,20 @@ # Release Notes -This release makes no changes to the OpenAPI standard, however the formal specification document had multiple improvements, including: +While the 3.1.1 release makes no mechanical changes to the OpenAPI 3.1.0 specification, it does introduce a number of notable improvements, including: - clarity and expanded explanations including several new appendices with supplementary details -- examples and additional documentation moved to https://learn.openapis.org -- the HTML rendering of the specification at https://spec.openapis.org is now considered the authoritative version (formerly it was the Markdown source on GitHub) +- Focuses on technical specifics by moving examples and additional documentation now published at https://learn.openapis.org +- Declares that the HTML specifications at https://spec.openapis.org are now the authoritative versions (formerly it was the Markdown source on GitHub) OpenAPI description writers should mark their OpenAPI descriptions with the version of OpenAPI specification they used to write their specification, updating where possible. -Tool creators should also not expect changes, but it is recommended to check the list of changes below. +Tooling maintainers should expect minimal work to support 3.1.1/3.0.4; however, we recommend checking the list of changes below. ## Clearer Definitions Introduce consistent language around OpenAPI Document/Description/Definition: - OpenAPI Description means the OpenAPI description of an API, whether it is in one or many files. -- a document means a single file. -- an "entry document" is where the OpenAPI description for an API starts; it may reference other documents. +- A document means a single file. +- An "entry document" is where the OpenAPI description for an API starts; it may reference other documents. Improved language regarding schemas, explaining the difference between the OpenAPI schema, the schemas used within the OpenAPI schema, and the use of a non-authoritative JSON Schema to supplement the written spec. @@ -23,7 +23,9 @@ Improved language regarding schemas, explaining the difference between the OpenA ## References Additional guidance for resolving references and parsing documents was added. + Resolving component names, tags, and operationIds are clarified. + [3.1.1]The adoption of JSON Schema in 3.1.x changed the parsing and referencing, and a new section was added to cover the changes in more depth than in 3.1.0. [3.1.1]Improved explanation of URLs and URIs, and made clear which to use for each URL/URI field. @@ -32,22 +34,25 @@ Clarified that Markdown links are resolved in relation to their rendered context ## Data Types Extensive clarifications on data types and encoding. + Added a section on handling binary data. ## Security -Added a note that the `security` array that is empty or missing values does not indicate that no security arrangements exist for this API. +Added a note that a `security` array that is empty or missing does not indicate that no security arrangements exist for this API. + Updated references to other standards where newer versions are available, and added more explanation for OpenIDConnect. -Added a "Security Concerns" section containing advice for implementers and users of OpenAPI. +Added a "Security Concerns" section containing advice for implementers and users of OpenAPI. ## Request Data -The parameters section was extensively refactored. -Examples were updated, improved and explanations added. +Extensive refactoring of the parameters section +Examples were updated, improved, and explanations added. + Headers have their own section with examples and specific information. -Explanation of OpenAPI `example` and `examples` was expanded and the "Working with Examples" section added with clearer description and examples included. +Improves and expands on OpenAPI `example` and `examples` and adds a "Working with Examples" section with a clearer description and examples. -Information regarding file uploads, form-urlencoded request bodies and multipart content were expanded and moved to the refactored Encoding Object section to provide better coverage of edge cases and more examples. +Clarifies and expands on file uploads, form-urlencoded request bodies, and multipart content, and moves them to a refactored `Encoding Object` section to provide better coverage of edge cases and more examples. From 05687b55f8a0321e46d17a82d56e333570ad5c73 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 17 Sep 2024 10:25:44 +0200 Subject: [PATCH 4/8] Apply suggestions from code review including the two I missed before Co-authored-by: Marsh Gardiner --- release-notes-3.1.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/release-notes-3.1.1.md b/release-notes-3.1.1.md index 9a2d92fe12..26c97774d4 100644 --- a/release-notes-3.1.1.md +++ b/release-notes-3.1.1.md @@ -1,11 +1,11 @@ # Release Notes While the 3.1.1 release makes no mechanical changes to the OpenAPI 3.1.0 specification, it does introduce a number of notable improvements, including: -- clarity and expanded explanations including several new appendices with supplementary details +- Expands and clarifies a number of explanations, including several new appendices with supplementary details - Focuses on technical specifics by moving examples and additional documentation now published at https://learn.openapis.org - Declares that the HTML specifications at https://spec.openapis.org are now the authoritative versions (formerly it was the Markdown source on GitHub) -OpenAPI description writers should mark their OpenAPI descriptions with the version of OpenAPI specification they used to write their specification, updating where possible. +OpenAPI description writers should mark their OpenAPI descriptions with the version of the OpenAPI specification they used to write their specification, updating where possible. Tooling maintainers should expect minimal work to support 3.1.1/3.0.4; however, we recommend checking the list of changes below. From 5a57fb0c5a26bf489319126c46b940b618829825 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 18 Sep 2024 10:04:08 +0200 Subject: [PATCH 5/8] Update release-notes-3.1.1.md --- release-notes-3.1.1.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/release-notes-3.1.1.md b/release-notes-3.1.1.md index 26c97774d4..ada8a4c201 100644 --- a/release-notes-3.1.1.md +++ b/release-notes-3.1.1.md @@ -22,10 +22,7 @@ Improved language regarding schemas, explaining the difference between the OpenA ## References -Additional guidance for resolving references and parsing documents was added. - -Resolving component names, tags, and operationIds are clarified. - +Additional guidance for resolving references and parsing documents was added, resolving component names, tags, and operationIds are clarified. [3.1.1]The adoption of JSON Schema in 3.1.x changed the parsing and referencing, and a new section was added to cover the changes in more depth than in 3.1.0. [3.1.1]Improved explanation of URLs and URIs, and made clear which to use for each URL/URI field. From 501362d7a7a97778a59fe4349f074e6b4757ed30 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 19 Sep 2024 09:52:09 +0200 Subject: [PATCH 6/8] Apply suggestions from code review --- blog-post.md | 12 +++++++----- release-notes-3.1.1.md | 6 +++--- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/blog-post.md b/blog-post.md index f312e9f7fa..ab76632c41 100644 --- a/blog-post.md +++ b/blog-post.md @@ -1,10 +1,10 @@ The OpenAPI Initiative is pleased to announce a patch release of the 3.0 and 3.1 OpenAPI specifications. -In patch releases, no changes are made to the way that APIs are described, but the specification wording itself contains many updates, expansions, and clarifications where previous the points may have been unclear or not covered. +In patch releases, no changes are made to the way that APIs are described, but the specification wording itself contains many updates, expansions, and clarifications where previously the points may have been unclear or not covered. Think of this release as the "Words Mean Things" edition. ## Released versions -3.1.1 is the newest and recommended version of OpenAPI. +3.1.1 is the newest and recommended version of the OpenAPI Specification. If you are starting a new project today, or have the option to upgrade, this is your target version. Tooling that supports 3.1.0 is expected to work without problems on 3.1.1 since the patch releases don't contain structure changes. @@ -13,19 +13,19 @@ It is expected that 3.0.4 will be the final release in the 3.0.x line. ## Summary of changes -The releases include as many explanations, clarifications and expanded sections as we could manage, driven mostly by the questions and comments we get from the users and tools creators of OpenAPI. +The releases include as many explanations, clarifications and expanded sections as we could manage, driven mostly by the questions and comments we get from the users and tools creators of the OpenAPI Specification. The highlights include a lot of new content to expand on existing content and reduce ambiguity. The sections regarding parameters, encoding and schemas have had significant updates and expansion to cover more cases. You will also find some security clarifications and a whole new "Security Considerations" section has been added. Look out for additional appendices with some great explanations that support the additions to the main body of the specification. We added a great collection of new content sections and appendix entries about handling data including data types, serialization and encoding. -In 3.1, there is more information about parsing documents and resolving references since the adoption of JSON Schema. +In 3.1, there is more information about parsing documents and resolving references since the adoption of full JSON Schema compatibility. The updates also strayed into distinctly "meta" areas, so we've also got: - examples of using the `example(s)` fields -- reference to a schema to represent the OpenAPI schema +- reference to a JSON Schema to represent the OpenAPI Specification schema - we have clearly defined when something was undefined or implementation dependent ## Beyond the specification @@ -38,6 +38,8 @@ In addition to the main specifications that you can always find at https://spec. This representation should not require changes between 3.1.0 and 3.1.1 since patch releases don't change the structure. - The [formats registry](https://spec.openapis.org/registry/format/index.html) and the [extensions registry](https://spec.openapis.org/registry/extension/index.html) list some common patterns in specification use. +All of these resources are now linked from the relevant parts of the OpenAPI Specification. + We also updated the tooling that publishes the specification, changed the GitHub repository structure, cleaned up and reformatted all the Markdown content, and improved our workflow automation. Which doesn't affect the specification but does make it a nicer place to be and hopefully makes the next release easier too. diff --git a/release-notes-3.1.1.md b/release-notes-3.1.1.md index ada8a4c201..37c473d26e 100644 --- a/release-notes-3.1.1.md +++ b/release-notes-3.1.1.md @@ -1,11 +1,11 @@ # Release Notes -While the 3.1.1 release makes no mechanical changes to the OpenAPI 3.1.0 specification, it does introduce a number of notable improvements, including: +While the 3.1.1 release makes no changes to requirements of the OpenAPI 3.1.0 specification, it does introduce a number of notable improvements, including: - Expands and clarifies a number of explanations, including several new appendices with supplementary details - Focuses on technical specifics by moving examples and additional documentation now published at https://learn.openapis.org - Declares that the HTML specifications at https://spec.openapis.org are now the authoritative versions (formerly it was the Markdown source on GitHub) -OpenAPI description writers should mark their OpenAPI descriptions with the version of the OpenAPI specification they used to write their specification, updating where possible. +OpenAPI Description writers should mark their OpenAPI Descriptions with the version of the OpenAPI specification they used to write their specification, updating where possible. Tooling maintainers should expect minimal work to support 3.1.1/3.0.4; however, we recommend checking the list of changes below. @@ -14,7 +14,7 @@ Tooling maintainers should expect minimal work to support 3.1.1/3.0.4; however, Introduce consistent language around OpenAPI Document/Description/Definition: - OpenAPI Description means the OpenAPI description of an API, whether it is in one or many files. - A document means a single file. -- An "entry document" is where the OpenAPI description for an API starts; it may reference other documents. +- An "entry document" is where the OpenAPI Description for an API starts; it may reference other documents. Improved language regarding schemas, explaining the difference between the OpenAPI schema, the schemas used within the OpenAPI schema, and the use of a non-authoritative JSON Schema to supplement the written spec. From 55e533edc81b83840630b3ef333956b071c3c49a Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Thu, 19 Sep 2024 16:16:03 +0100 Subject: [PATCH 7/8] Put the tooling remark earlier --- blog-post.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/blog-post.md b/blog-post.md index ab76632c41..3df8d7c6aa 100644 --- a/blog-post.md +++ b/blog-post.md @@ -1,12 +1,13 @@ The OpenAPI Initiative is pleased to announce a patch release of the 3.0 and 3.1 OpenAPI specifications. In patch releases, no changes are made to the way that APIs are described, but the specification wording itself contains many updates, expansions, and clarifications where previously the points may have been unclear or not covered. +Tooling that supports 3.1.0 is expected to work without problems on 3.1.1 since the patch releases don't contain structure changes. + Think of this release as the "Words Mean Things" edition. ## Released versions 3.1.1 is the newest and recommended version of the OpenAPI Specification. If you are starting a new project today, or have the option to upgrade, this is your target version. -Tooling that supports 3.1.0 is expected to work without problems on 3.1.1 since the patch releases don't contain structure changes. 3.0.4 is an additional release on the 3.0 branch to incorporate the improved wording to the 3.0 branch of the specification where the changes applied there. It is expected that 3.0.4 will be the final release in the 3.0.x line. From ef767d6945078571fd1740c2149fd15bfc159c22 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Thu, 19 Sep 2024 16:20:45 +0100 Subject: [PATCH 8/8] Fix formatting, make URLs into links --- blog-post.md | 4 ++-- release-notes-3.1.1.md | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/blog-post.md b/blog-post.md index 3df8d7c6aa..eb0bed39cb 100644 --- a/blog-post.md +++ b/blog-post.md @@ -31,9 +31,9 @@ The updates also strayed into distinctly "meta" areas, so we've also got: ## Beyond the specification -In addition to the main specifications that you can always find at https://spec.openapis.org, there are a number of other resources that you may find helpful: +In addition to the main specifications that you can always find at [spec.openapis.org](https://spec.openapis.org), there are a number of other resources that you may find helpful: -- OpenAPI's documentation and examples is available at https://learn.openapis.org. +- OpenAPI's documentation and examples is available at [learn.openapis.org](https://learn.openapis.org). This site holds all the examples used in the main OpenAPI specification, and much more additional information besides. - A [non-authoritative JSON Schema representation of the OpenAPI specification](https://spec.openapis.org/#non-normative-json-schemas) is available. This representation should not require changes between 3.1.0 and 3.1.1 since patch releases don't change the structure. diff --git a/release-notes-3.1.1.md b/release-notes-3.1.1.md index 37c473d26e..48fc22e1fb 100644 --- a/release-notes-3.1.1.md +++ b/release-notes-3.1.1.md @@ -2,8 +2,8 @@ While the 3.1.1 release makes no changes to requirements of the OpenAPI 3.1.0 specification, it does introduce a number of notable improvements, including: - Expands and clarifies a number of explanations, including several new appendices with supplementary details -- Focuses on technical specifics by moving examples and additional documentation now published at https://learn.openapis.org -- Declares that the HTML specifications at https://spec.openapis.org are now the authoritative versions (formerly it was the Markdown source on GitHub) +- Focuses on technical specifics by moving examples and additional documentation now published at [learn.openapis.org](https://learn.openapis.org) +- Declares that the HTML specifications at [spec.openapis.org](https://spec.openapis.org) are now the authoritative versions (formerly it was the Markdown source on GitHub) OpenAPI Description writers should mark their OpenAPI Descriptions with the version of the OpenAPI specification they used to write their specification, updating where possible. @@ -41,6 +41,7 @@ Added a note that a `security` array that is empty or missing does not indicate Updated references to other standards where newer versions are available, and added more explanation for OpenIDConnect. Added a "Security Concerns" section containing advice for implementers and users of OpenAPI. + ## Request Data Extensive refactoring of the parameters section