OAI
"body parameter" example in 3.x does not fit how Request Body Objects work
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?
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/*')!
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.
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?
@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:
- #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.
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.