Skip to content

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

@hkosova

Description

@hkosova
Contributor

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?

Activity

handrews

handrews commented on Jul 5, 2020

@handrews
Member

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

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

handrews commented on Jun 21, 2024

@handrews
handrews

handrews commented on Jun 21, 2024

@handrews
Member

oops - commented on / closed the wrong issue

handrews

handrews commented on Jun 21, 2024

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

lornajane commented on Sep 5, 2024

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

Metadata

Metadata

Assignees

Labels

clarificationrequests 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)review

Type

No type

Projects

No projects

Relationships

None yet

    Development

    No branches or pull requests

      Participants

      @lornajane@handrews@hkosova

      Issue actions

        Questions about schemas for multipart and application/x-www-form-urlencoded request bodies · Issue #2282 · OAI/OpenAPI-Specification