feat(spec): codify Encoding in specific requestBody mediatypes #3834
Conversation
This file contains hidden or 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
(port of PR #2127 to v3.1)
Added Oxygen OpenAPI editor
See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/1.2.md#523-operation-object. The maximum of 120 characters is a "SHOULD", which according to RFC 2119 is a mere recommendation.
Co-authored-by: webron <[email protected]>
* format:base64 doesn't exist -> format:byte * Remove lines without format from Data Formats table
The IETF apparenlty decided to redo everything about publishing RFCs, and while most of the old URLs redirect, these ones for RFC 3339 did not. Also, there was a stray trailing '/' that broke another RFC link.
Same fix has already been applied to 3.1.1-dev
Add a brief explanation as a subsection of Data Types, and update the relevant examples. Specifically: * Don't use `format: byte` for a whole message body * Fix `multipart/mixed` example to be `multipart/form-data` (because `multipart/mixed` does not name its parts and therefore cannot be represented with an object schema) * Add an `application/x-www-form-urlencoded` example, which is where `format: byte` needs to be used
Co-authored-by: John Charman <[email protected]>
This follows up from a discussion on the OAI slack that decided: * redefining "document" to sometimes mean multiple documents is confusing * "description" has more support than "definition"
same as #3375
These should have the parameter name in the resulting string (see issue #3737).
If no Encoding Object is provided, the behavior is the same as an empty Encoding Object, as none of its fields are required.
Co-authored-by: Mike Kistler <[email protected]>
The "undefined" wording was chosen to allow implementations that make a good-faith effort to accommodate non-string values to remain compliant. However, new implementations are not expected to implement any sort of type coersion, and this guides API designers away from that expectation.
Co-authored-by: Ralf Handl <[email protected]>
The previous wording could be read to only restrict what sort of request bodies could use an Encoding Object, while allowing that it could be used with other entities that use a Media Type Object. This emphasizes that it is only relevant to Request Body Objects, and within that, only for specific media types. # Conflicts: # versions/3.0.4.md
Co-authored-by: Mike Kistler <[email protected]>
The OAS does not define how to avoid collisions between parameter values and style delimiters. Mostly, this is straightforward, but the need to URL encode space characters introduces extra confusion. Make it clear that managing this occurs outside of the use of style, and is the responsibility of users.
Co-authored-by: Ralf Handl <[email protected]>
This is a more natural grouping of similar types, making the data much easier to read. # Conflicts: # versions/3.0.4.md
# Conflicts: # .gitignore
This makes the relational requirements of `content` vs `schema` and associated fields more clear. The mutual exclusivity requirement is moved up to the top of the Fixed Fields section, and each table table is given a subsection clarifying its meaning. This makes it easier to follow the multi-table format, which is unusual within the OAS. The commentary on `example` and `examples` is moved to the section on `schema` and related parameters as it appears to only apply in that case.
Undefined means "don't use this even if it seems to work, as there are cases where it won't." Implementation-defined means "this isn't portable or interoperable, but it is still correct."
Co-authored-by: Ralf Handl <[email protected]>
and correct expansion of "auth"
This was missed in the 3.0.4 PR for this change, but caught in the 3.1.1 and 3.2.0 versions.
This clarifies the meaning of `allowEmptyValue` as discussed in today'd TDC call. It is intended to indicate an agreement between the client and server to use zero-length string values as an indicator of unused fields.
the specification indicates > The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded. Co-authored-by: Jeremy Fiel <[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.
the specification indicates
This PR codifies that behavior in the JSON Schema to enable validation.
Per the Development.md, this change was already merged to the Specification on this PR