OAI
feat(spec): codify Encoding in specific requestBody mediatypes
the specification indicates
The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded.
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
Minor concern that this would prevent */* as a media type. Generally supportive of this addition.
@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.
@handrews on this point:
@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.
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:
The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded.
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 ?
Since the spec uses "SHALL" and not "MUST"
Note that RFC2119 does not differentiate between these two words:
- MUST This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
We cannot base any decisions on this stylistic choice.
@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 encoding field is allowed but ignored in these circumstances, so it cannot be forbidden in the validation schema. But as @lornajane noted when closing those PRs, there is likely to be a home for this in some sort of separate linting schema or schemas:
Please keep an eye on the project for more discussion about linting schemas in addition to our validation schemas.