"body parameter" example in 3.x does not fit how Request Body Objects work

[handrews]

In the Request Body Examples section of both 3.0 and 3.1, the second example is as follows (JSON omitted for brevity):

---

A body parameter that is an array of string values:

description: user to add to the system
required: true
content:
  text/plain:
    schema:
      type: array
      items:
        type: string

---

This is identical to an example in the 2.0 spec, where the request body was treated as a parameter. I'm not entirely sure how it was supposed to be serialized even there, as the 3.x style and explode fields don't exist, but I definitely don't see how to serialize it in 3.0. There is no JSON Schema data model defined for text/plain, and nothing in the Request Body Object talks about how to serialize a list of values into plain text (Is it a comma-separated list? Is it one value per line?)

What was this example trying to show, and how can we show it more clearly?

[handrews]

@OAI/tsc review request: see above

[karenetheridge]

I expect some git spelunking (in an old swagger repo, perhaps)? might be needed to derive the original intent here. I agree it makes no sense at all - text/plain's serializer/deserializer is the identity function (and indeed my implementation has this hardcoded for 'text/*')!

[darrelmiller]

I do not believe this is a helpful example. I do not believe we have ever talked about how a JSON model should be serialized in text/plain payloads. We should make it a more useful example.

[mikekistler]

I agree that this is not a helpful example and we should make it more useful.

But I think there is a larger question here which is: how to interpret -- or whether to ignore -- schema for various media types. Does it make any sense for text/plain content to have any schema other than type: string? Likewise, for image/<anything> does it make any sense to have any schema other than type: string, format: binary?

In other words, I think that certain content types imply the schema -- maybe even impose a schema. I realize this is a much larger topic than just fixing an example, but shouldn't we address this somehow?

[handrews]

@mikekistler I have had similar thoughts that there's a general topic here. I wasn't going to bring it up yet, but since you did (and I'm glad to hear someone else have this sort of thought), I have started a discussion on a registry for data modeling:

• Registry of media type modeling approaches #3771

Let's have the larger discussion there (including the idea of certain types implying or imposing a schema, which is an interesting frame that had not occurred to me) and focus on just this example (which it sounds like there is consensus to remove) here.

[handrews]

I think the assessment is clear enough for me to remove the review label – I'll address this with several other media type encoding issues I'm working on.