Port 3.1.1 PRs to 3.2.0 #3987
Merged
Port 3.1.1 PRs to 3.2.0 #3987
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
The four ways of specifying parameter or media type examples are confusing. There is a lot of guidance that is repeated, making it harder to see the essentials. Some of that guidance is also contradictory, with most saying that the examples SHOULD match various conditions, but one saying that they MUST. Research shows that SHOULD was repeatedly advocated, and instances of MUST corrected back to SHOULD, except for one final commit where MUST was introduced, and the subsequent commit to revert to SHOULD seems to have simply missed one instance. So this change takes the position that the MUST was an error and weakens it to SHOULD to match the other four or five places where the requirement was specified.
Not only do we not capitalize the "h" elsewhere, this example, which pre-dated 3.1 webhooks, used the term in a confusinglty not-quite-the-same way.
…2 2/2) 3.1 deprecates the OAS extension `example` schema keyword in favor of the draft 2020-12 `examples` standard schema keyword.
This makes it more clear that jsonSchemaDialect, like $schema, is per document, and provides guidance for incomplete OAS documents and using $schema in standalone schema documents. It also clarifies the nature of "requiring" the OAS extension vocabulary. Co-authored-by: Karen Etheridge <[email protected]>
This copies the relevant Parameter Object fields to the Header Object instead of relying on implicit guidance. The text for the fields has been edited to reflect that only headers are being described. This also include an example of describing a header using the `content` field, and explaining why it is necessary to do so.
Co-authored-by: Ralf Handl <[email protected]>
* Replace the outdated "model" terminology with "schema" * Remove the outdated `text/plain` array example, which does not correlate with current OAS requirements * Rather than replacing the `text/plain` example direclty, enhance the example of serializing `application/json` content in `application/x-www-form-urlencoeded` request bodies.
This aligns allowReserved with style by similarly correlating it with RFC6570 operators. This will make it easier to write a more in-depth explanation of the process in an appendix. This also adds one of several appendixes to be added to clarify the most obscure details of Parameter Object and Encoding Object serialization. This clarifies the correspondence between OAS fields and RFC6570 operators, and acknowledges that some field values and combinations do not have analogues. It provides further guidance for how to use RFC6570 implementations to support these configurations. This includes a SHOULD directive regarding using RFC6570 expansion with the non-RFC6570 styles, as the use of "explode" and "allowReserved" does not otherwise make any sense. It perhaps could be a MUST. Examples are included to show both typical usage, and how to work around the lack of exact RFC6570 equivalences for certain configurations.
It's very unclear how numbers, booleans, and other non-UTF-8-string values are converted to strings, particularly for the form media types. This adds a brief appendix that acknowledges the lack of standardization, and points to resources for the few cases that do have specifications. It highlights concerns with relying on certain JSON Schema keywords or values for serialization, and suggests defining schemas of type string and requiring applications to perform the conversion prior to schema validation as a way to control the results. This also clarifies that schema validation occurs before serialization. Also add note about RFC6570 type conversions. The spec doesn't address it, but implementations often have their own rules.
This makes serializing cookie paramters and most header parameters with `schema` and `style` NOT RECOMMENDED. It is not clear that any `schema`-based serialization for cookies will produce a correct value (although the reason is sufficiently obscure that many implementations might ignore it and produce cookie-compliant output anyway). With headers, there are numerous pitfalls and only the simplest scenarios will work properly, although perhaps the warning here could be reworded to emphasize the safe scenarios more clearly. The details are relegated to an appendix, because truly, most people will not want to know. But recommending against syntactically legal configurations really does need to be explained in the spec. Also, don't use - in: header name: Cookie Because... yeah.
This adds the previously standalone security considerations document as a top-level section just before the appendices.
Guide readers to supplemental documentation, examples, related specificatioins, and extension registries. These sites answer many questions that otherwise get raised as GitHub issues.
Co-authored-by: Lorna Jane Mitchell <[email protected]>
…3861 7/11) Co-authored-by: Ralf Handl <[email protected]>
Thanks to @lornajane for the review feedback.
When we mention YAML's "Failsafe schema" we give it a lower-case "schem", as the YAML documentatio does. We also prefix it with "YAML". However, we capitalize "Schema" in "JSON Schema ruleset", which (given how much JSON Schema is used in the OAS) is a jarring overlap with "JSON Schema". This change aligns "YAML JSON schema ruleset" with "YAML Failsafe ruleset" and explicitly calls out that it is unrelated to JSON Schema.
… 1/4) The Encoding Object's `contentType` field takes a comma-separated list of either regular or wildcared media types. These are the "two types" mentioned in the previous wording – "two" here did *not* refer to a limit on the number of entries in the list. These are not exactly media-type or media-range values, as both of those include parameters. This change also moves the hard-to-follow list of default values out of the individual field cell and into its own table. It takes `Content-Disposition` out of the header field's cell and instead explains limitations on header usage, and explains how `Content-Disposition` is used for encoding. This explanation includes a suggestion on how other `multipart` formats could be used with an Encoding Object, since their unnamed parts otherwise cannot be supported. Finally, it clarifies the interaction between `contentType` and the three fields imported from the Parameter Object, by aligning the recommended (but not, for compatibility reasons, required) behavior with guidance added in 3.1.0.
Thanks to @notEthan for the comments!
This splits the Encoding Object's fixed fields table to make the usage more clear, and closer to how it is presented for the Parameter and Header Objects
Percent-encoding is a minefield, although in practice it mostly works. This appendix attempts to acknowledge the concerns and then define enough terminology and link to enough other specifications that interested readers will be able to research further details.
This aligns all examples with RFC6570 operator prefixing behavior, which was previously only shown for `matrix` and `label`. The non-RFC6570 styles (`spaceDelimited`, `pipeDelimited`, and `deepObject`) are treated as analogues of `form` and therefore prefixed with a `?`. The lack of suitablity of this for cookie parameters has been addressed with an appendix in another change, and the appendix has been stubbed out here to ensure that the link is valid. Switch the "empty" column heading to "undefined" to align with RFC6570 and make clear that it is not about `allowEmptyValue`
Co-authored-by: Ralf Handl <[email protected]>
This tries to be consistent about using "describe" rather than "define" and using "description" for the entire potentially-multi-document thing, and "document" (or sometimes "description document") to refer to individual documents in the description.
This adds a note about the authoritative HTML rendering and adds a definition for "Schema" to explain the three ways the term is used in or with the specification.
This just moves (and occasionally copies) blocks of text and/or examples in preparation form more substantial streamlining. No modifications were made to any block.
Make the Parameter, Encoding, and Header Object fixed fields section organization the same in all three places, with the same levels of indentation. Add more headings under the Encoding Object for guidance on each form media type, and sub-headings for each example in each of those sections. This will make the diff for the next commit much more legible.
This puts the useful part of the "An encoding attribute..." text into the fixed fields table, and removes the duplication. It also links the remaining stub or truncated sections to the information's new location under the Encoding Object.
This re-organizes and streamlines the form-urlencoded guidance that was consolidated from the Media Type Object. It also adds an example of a base64-encoded URL query parameter.
I forgot to run the example through URL quoting, which is necessary.
This organizes and streamlines the guidance on multipart that was incorporated from the Media Type Object. Lots of duplication has been removed, and the examples reworked to show distinct use cases.
As discovered through the OASComply project, certain referencing scenarios are ambiguous, with different authorities holding contradictory interpretations regarding whether and how they are to be supported. As a result, it is impossible to define compliance, as all of the interpretations can be argued to be "correct" in some sense. This change excludes some particularly challenging scenarios from compliance testing by making their behavior explicitly implementation-defined. This has several benefits: * No current implementation is rendered non-compliant * No currently usable OAD is rendered invalid * New implementers need not put effort into handling these scenarios * User expectations are set to _not_ expect consistent behavior * Linters can write a rule to match these expectations * Everyone is guided towards straightforwad best practices
Co-authored-by: Ralf Handl <[email protected]>
JSON Schema draft 2020-12 includes numerous keywords that require parsing the entire document prior to deeming a reference unresolvable. This makes that more clear and outlines several approaches. The practice of embedding OpenAPI fragments in other formats is deemed to have implementation-defined (non-interoperable) behavior, as the potential complications that might arise are not predictable. Also provide guidance around fragmentary parsing. This goes into more detail and uses "undefined" instead of "implementation-defined" as the behavior is likely to be incorrect (rather than just a different interpretationof an ambiguous requirement), and may result in security concerns as well.
Clarifies that there can be multiple complete OpenAPI documents, only one of which is an entry OpenAPI document.
This clarifies that using the APIs involves URLs, while describing the API involves URIs. It ensures that all URIs involved in the API description are called "URIs", and briefly mentions how using URIs is different from URLs.
Note that they are resolved in their rendered context.
This clarifies how to handle resolving implicit (non-URI-based) connections in multi-document OpenAPI Descriptions. While the behavior is implementation-defined overall, this RECOMMENDS a single approach based on how things behaved going back to the 2.0 referencing model. This allows Security Schemes and Tags to (like the top-level Server Objects) define a deployment-specific interface for referenced documents to access. This entry document interface approach makes less sense for the Discriminator Object, but it can use the URI syntax of `mapping` to keep things within the local document. This also aligns the search for matching `operationId`s with 3.1's full-document parsing requirements. Note that the term "complete OpenAPI document" has been defined in another change pending approval on the 3.0.4 branch.
Review feedback from Jeremy Fiel and typo fix from Ralf Handl. Co-authored-by: Jeremy Fiel <[email protected]>
Includes examples as either YAML or JSON via HTTP negotiation
Co-authored-by: Jeremy Fiel <[email protected]>
handrews
added
the
approved pr port
miqui
approved these changes
Aug 13, 2024
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.
This should include almost all PRs that went into 3.1.1 except for the most recent ones synchronizing wording between 3.0.4 and 3.1.1 (I tried adding those but git couldn't figure out how to apply the commits so the wording changes probably aren't quite the same for 3.2.0 and will need to be done separately).
All of the referencing-related PRs are ported at the end (I was going to make 2 PRs at one point, but decided to consolidate it all). You might have to click "Load more commits" to see them in the commit list below.
As with the larger 3.0.4->3.1.1 ports, all of the original commits are preserved and note the original 3.0.4 or 3.1.1 PR for reference.
The only substantive PR that is not ported is the change in deprecation status for the Path Item
$ref, which is not a straight port and is being tracked separately in issue #3734.