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

Questions about schemas for multipart and application/x-www-form-urlencoded request bodies #2282

Closed
hkosova opened this issue Jul 5, 2020 · 5 comments
Assignees
Labels
clarification requests to clarify, but not change, part of the spec media and encoding Issues regarding media type support and how to encode data (outside of query/path params) review
Milestone

Comments

@hkosova
Copy link
Contributor

hkosova commented Jul 5, 2020

1. The Special Considerations for multipart Content section says:

In contrast to 2.0, a schema is REQUIRED to define the input parameters to the operation when using multipart content.

Please consider including this requirement in the description of Media Type Object.schema, where it can be easily found.

2. Is schema also required for application/x-www-form-urlencoded request bodies?

3. All multipart/* and application/x-www-form-urlencoded examples in the spec use schemas with type: object, where schema properties define individual form fields. Does this mean that type: object is the only allowed schema type for these media types? If yes, please consider mentioning this explicitly somewhere. If not, how would other schema types work here?

@handrews
Copy link
Member

handrews commented Jul 5, 2020

@hkosova I reworked a lot of that section in PR #2200 for OAS 3.1. I'm not sure I addressed these questions but you might want to take a look at the changes as things might show up differently now.

As for my personal thoughts off the top of my head:

  1. I think this is a question of defaulting. If a missing schema is the same as an empty schema (the usual defaulting approach JSON Schema) which allows everything, then omitting it means the request body might have any content. A false schema in OAS 3.1 (or {"not": {}} in OAS 3.0 or earlier) would then be needed to forbid a request body. I'd personally recommend doing that- if you want to constrain the set of valid request bodies, you need a schema. Otherwise it's an empty schema by default so it could be anything.

  2. I believe it's simply that no other type makes sense. I'd avoid saying that type: object is the only allowed type, as someone could theoretically figure out something else that makes sense. Maybe. What I'd prefer here is to talk about how multipart/* and application/x-www-form-urlencoded media types map into the JSON Schema data model. Once you do that, the relevant type value or values should be obvious. If you write a thing that can only be mapped into an object, then of course type: object is the only useful type. It's not a special case, it just flows naturally. I'd be happy to help work on wording for this if there is interest.

@handrews handrews added clarification requests to clarify, but not change, part of the spec media and encoding Issues regarding media type support and how to encode data (outside of query/path params) labels Jan 28, 2024
@handrews handrews self-assigned this May 24, 2024
@handrews handrews added this to the v3.0.4 milestone May 24, 2024
@handrews

This comment was marked as off-topic.

@handrews
Copy link
Member

handrews commented Jun 21, 2024

oops - commented on / closed the wrong issue

@handrews handrews reopened this Jun 21, 2024
@handrews
Copy link
Member

@OAI/tsc review request: I'm not quite sure what to do with this.

Part of it is addressed by recent changes - we note that the correlation is by object property. Although I'm not quite sure I say outright anywhere that nothing else could possibly work.

As for making it more clear that a schema is required- I'm not entirely sure it is? See the question about how the lack of schema would be treated in my comment above.

@lornajane
Copy link
Contributor

Discussed in the TDC meeting, and we think the recent changes in this space cover the things that we can be very specific about, and we want to leave this otherwise as it is.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
clarification requests to clarify, but not change, part of the spec media and encoding Issues regarding media type support and how to encode data (outside of query/path params) review
Projects
None yet
Development

No branches or pull requests

3 participants