feat(spec): codify Encoding in specific requestBody mediatypes #3837
Conversation
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: Fiel, Jeremy <jeremy.fiel@ADP.com>
|
Also paging @karenetheridge |
schemas/v3.0/schema.yaml
Outdated
| patternProperties: | ||
| '^application/x-www-form-urlencoded$|^multipart\/.+$': | ||
| $ref: '#/definitions/MediaTypeWithEncoding' |
|
Minor concern that this would prevent |
|
@OAI/tsc I think what is needed here is a policy on whether field combinations that are said to be ignored or to not apply can be forbidden by the schema or not. That would help us decide a lot of schema design issues, rather than having to re-think each proposed restriction. There are quite a few places in the spec with this kind of language, and we should treat them consistently in the schemas. I'd be fine with either way the TSC wants to decide this - if it is decided that ignored/non-applicable things can be forbidden in the schema, then I'm fine with this PR being merged. |
schemas/v3.0/schema.yaml
Outdated
| @@ -763,6 +783,9 @@ definitions: | |||
| type: object | |||
| additionalProperties: | |||
| $ref: '#/definitions/MediaType' | |||
| patternProperties: | |||
| '\*\/\*|^application/x-www-form-urlencoded$|^multipart\/.+$': | |||
There was a problem hiding this comment.
Should */* have ^/$ anchors?
Should application/* be matched, as that would apply to application/x-www-form-urlencoded?
There was a problem hiding this comment.
what is the purpose of the anchors? Why would it be needed?
I see your point on the above. I'll update that
application/* would match any application media type and that's not what we want here., although that would enable quite a few different media types to allow encoding schema. Matching */* was only for backwards compatibility per Darrell's comment.
|
@handrews on this point:
My opinion is that if the spec says a field combination must be ignored or not apply, then we can make these forbidden by the schema. |
|
Following up here ... what I see in the v3.0.3 spec is:
Since the spec uses "SHALL" and not "MUST", and my prior comment, I think my view is that we should NOT make this change to the schema, at least for v3.0. Do you agree @jeremyfiel ? |
Note that RFC2119 does not differentiate between these two words:
We cannot base any decisions on this stylistic choice. |
|
Thanks Ralf and Mike for reviewing and your comments. |
|
@mikekistler MUST be ignored is not the same as forbidden. I don't think we can forbid anything in the schema on the grounds that it is to be ignored. Those are two different things. Again, if we want to supply two schemas, one that only constrains what is required by the OAS, and one that has additional constraints that help avoid pitfalls, I think that would be a great idea. But I think it is incorrect to over-constrain the schema if it is the only schema. (I realize this is a bit different from what I said earlier, but there are a whole bunch of "MUST be ignored" in the OAS, and if we start changing the schema based on that, that is a huge amount of change, and I think an incorrect change). |
|
Based on today's TDC call, I'm going to close this for the same reasons as #4069 and #4070. Technically, the
|
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