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

[hkosova]

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]

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

2. 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.

3. 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]

oops - commented on / closed the wrong issue

[handrews]

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

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.