-
Notifications
You must be signed in to change notification settings - Fork 9.1k
Closed
Labels
clarificationrequests to clarify, but not change, part of the specrequests to clarify, but not change, part of the specmedia and encodingIssues regarding media type support and how to encode data (outside of query/path params)Issues regarding media type support and how to encode data (outside of query/path params)review
Milestone
Description
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 usingmultipart
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?
Metadata
Metadata
Assignees
Labels
clarificationrequests to clarify, but not change, part of the specrequests to clarify, but not change, part of the specmedia and encodingIssues regarding media type support and how to encode data (outside of query/path params)Issues regarding media type support and how to encode data (outside of query/path params)review
Type
Projects
Relationships
Development
Select code repository
Activity
handrews commentedon 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:
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.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 howmultipart/*
andapplication/x-www-form-urlencoded
media types map into the JSON Schema data model. Once you do that, the relevanttype
value or values should be obvious. If you write a thing that can only be mapped into an object, then of coursetype: 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 commentedon Jun 21, 2024
handrews commentedon Jun 21, 2024
oops - commented on / closed the wrong issue
handrews commentedon Jun 21, 2024
@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 commentedon Sep 5, 2024
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.