Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
handrews opened this issue Apr 27, 2024 · 7 comments
Closed
Assignees
Labels
bug examples requests for more or better examples in the specification media and encoding Issues regarding media type support and how to encode data (outside of query/path params)
Milestone

Comments

@handrews
Copy link
Member

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 handrews added bug examples requests for more or better examples in the specification media and encoding Issues regarding media type support and how to encode data (outside of query/path params) labels Apr 27, 2024
@handrews handrews added this to the v3.0.4 milestone Apr 27, 2024
@handrews handrews self-assigned this Apr 27, 2024
@handrews
Copy link
Member Author

@OAI/tsc review request: see above

@karenetheridge
Copy link
Member

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
Copy link
Member

darrelmiller commented Apr 28, 2024

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
Copy link
Contributor

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
Copy link
Member Author

handrews commented May 1, 2024

@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:

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 handrews removed the review label May 2, 2024
@handrews
Copy link
Member Author

handrews commented May 2, 2024

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.

@handrews
Copy link
Member Author

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug examples requests for more or better examples in the specification media and encoding Issues regarding media type support and how to encode data (outside of query/path params)
Projects
None yet
Development

No branches or pull requests

4 participants