Why can't one use a "schema" or "type=object" for formData parameters?

[Jonathan Ingram]

I thought I'd start with the API I'm trying to represent:

We allow creating new jobs from a file upload, a JSON job object, or both (within the one call). E.g. in CURL something like this would be used when sending both the file and the JSON:

curl -X POST https://example.com/api/jobs/ \

  -F file=@job.txt \

  -F body='{ "title": "Foobar developer", "content": "Expert at developing foobars...", "props": { "internalId":"123abc" } }'

If it's not obvious, the reason is because we need to allow sending files in the request body so we can't just have the entire request body as a JSON string. And we name the form field "body" because if it effectively is the entire body - it's just a technicality that we also have to put files in there.

I imagine example swagger parameters would be (maybe these are wrong?):

"parameters": [{

  "name": "file",

  "in": "formData",

  "description": "The file to parse when creating a new job",

  "required": false,

  "type": "file"

}, {

  "in": "formData",

  "name": "body",

  "description": "Job data, e.g. title, content, props. The data in here is augmented with the data parsed out of the file.",

  "required": false,

  "schema": {

   "$ref": "#/definitions/Job"

  }

}],

(don't be confused by the "file" and "body" names above - they just match the form fields in the CURL call).

You could then imagine an API playground UI that would let you 1) choose a file to upload and 2) individually fill out the job fields "title", "content", etc. (which then get JSON encoded before sending) - i.e. the playground wouldn't make you write JSON in a text box.

So then, per https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields-7

A. The "schema" field only applies if `in` is "body".

B. If `in` is any value other than "body", for the "type" field:

Since the parameter is not located at the request body, it is limited to simple types (that is, not an object).

This suggests to me that because of A., my putting a "schema" in the second parameter above actually has no impact and should be ignored by swagger implementations. 

But, why would B. be required? Why can't a form data field be an encoded JSON object like I have in the CURL request above?

I feel like I'm missing something as surely I'm not the first person to come across this and try and do this (couldn't find any similar topics or issues though). Or maybe everything I'm doing is legal.

Thanks,

Jon

[tony tam]

Hi Jon, you’re not the first person to ask this.  We did not add support for complex form-data parameters because there is no standard or standard practice for representing them.  As with query parameters, it is difficult to represent anything other than primitive types as form-data.

That said, it is a common request.  The OAI specification can get more opinionated on a way to do this, but it’ll make as many people unhappy as it makes happy (if we’re lucky) since many camps do not support this mechanism.

My ask is that you find a ticket in the OAI repo and up vote it.  We’re reviewing all these requests right now and will add support where we feel it adds the most possible benefits.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.