Explicitly state that Media Type Object schema field applies to responses as well as requests #1579
Conversation
…nses as well as requests.
versions/3.0.2.md
Outdated
| @@ -1363,7 +1363,7 @@ Each Media Type Object provides schema and examples for the media type identifie | |||
| ##### Fixed Fields | |||
| Field Name | Type | Description | |||
| ---|:---:|--- | |||
| <a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body. | |||
| <a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body (or response body, if this is part of a response). | |||
There was a problem hiding this comment.
Note that Media Type Object is also used in Parameter Object, in cases where the parameter is specified by the content map, as opposed to schema and style. The content property is a Map[string, Media Type Object].
Maybe it would be simpler to say:
"The schema defining the content of the request, response, or parameter."
There was a problem hiding this comment.
Good catch, sir. :)
There was a problem hiding this comment.
I like that wording a lot better, actually, because the old wording:
The schema defining the type used
Implies that the schema uniquely identifies the "type" of a request, response, or parameter, but since a schema can validate multiple types, it doesn't really.
|
I think #1576 identifies some confusion in this area as well. It should perhaps be a separate PR but as I'm confused on the topic myself I thought I'd use this to draw more attention to it. TL;DR: To me, the schema of the media type object should have nothing to do with whether the media is streamed or not, but apparently that's a thing? |
Super minor nit-picky sort of change. :)