Encoding Object: should only be allowed in Request body object, mediaType: multipart OR x-www-form-urlencoded

[jeremyfiel]

... refer to next comments

[jeremyfiel]

ok, so another interesting twist on this validation.. the spec states encoding is only valid for request object and multipart or application/x-www-form-urlencoded

i was trying to add it to a response, so it looks like this is not valid and should be flagged.

edited...

[jeremyfiel]

...

[jeremyfiel]

i figured it out .. i was missing the headers mapping key

"content": {
	"multipart/mixed": {
		"schema": {
			"type": "object",
			"properties": {
				"file": {
					"type": "string",
					"format": "binary"
				},
				"_confirmMessage": {
					"$ref": "../../../common/shared/confirm-message-schema_v03.json"
				}
			},
			"additionalProperties": false,
			"required": [
				"file",
				"_confirmMessage"
			]
		},
		"encoding": {
			"file": {
				"headers": {
					"Content-Disposition": {
						"$ref": "#/components/headers/Content-Disposition"
					}
				},
				"contentType": "application/xml; charset=utf-8"
			},
			"_confirmMessage": {
				"contentType": "application/json"
			}
		}

but I still think there is an opportunity to increase the validation of Redocly tooling to restrict the encoding object to RequestBody Objects per the spec.

The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form- urlencoded.

[RomanHotsiy]

Good point @jeremyfiel.

We'll increase the validation for sure!

[jeremyfiel]

related https://github.com/Redocly/redoc/issues/2444

[tatomyr]

Hey @jeremyfiel, does a configurable rule like the following solve your problem?

rules:
  rule/encoding:
    subject:
      type: MediaType
      filterInParentKeys:
        - application/json
    assertions:
      disallowed:
        - encoding

[jeremyfiel]

Sure, the rule works ok but this should be part of the OAS validation by the tooling. It's part of the spec that's not validated today by Redocly, as far as I can tell.

[tatomyr]

I'm reluctant to write yet another built-in rule for that, or to extend the existing spec rule. What about introducing an extended 'recommended' ruleset that includes only configurable rules? I'm not sure though.

[lornajane]

The configurable rule is useful immediately, thanks @tatomyr!

I think this should be a standard check, but perhaps we can add a rule to our recommended set - this way, people can turn it off while they update their descriptions if it picks up problems.

[jeremyfiel]

Spec wording clarified in https://github.com/OAI/OpenAPI-Specification/pull/3724

Pending approval for updating the JSON Schema for validation purposes. https://github.com/OAI/OpenAPI-Specification/pull/3837