add enum for collectionFormat

[fehguy]

Currently only CSV is listed. add the others...

[webron]

Here's a list of suggested values and their representation:

• default or json - foo=[bar, baz]
• csv (comma separated) - foo=bar,baz
• ssv (space separated) - foo=bar baz
• tsv (tab separated) (not sure this one makes sense) - foo=bar baz
• pipes - foo=bar|baz
• multiParam or just multi - foo=bar&foo=baz

Note that the multiple parameter example is normally accompanied by a parameter name with square brackets (such as foo[], however, that should be the explicit parameter name and not implied by the collectionFormat).

[fehguy]

@webron some thoughts.

• I haven't seen the json syntax before. What framework have you seen that with?
• I've only seen the brackets with what you call the mutli syntax. Do you know of other uses of it?

i suggest we call default what you call the multi syntax. We call multi to include the brackets. We drop the json syntax, which I've not seen in practice. Thoughts?

[webron]

Taking a step back for a moment.

Currently, there are three places in the spec where arrays can be used - parameters, headers for responses and schemas (aka, models).

collectionFormat is currently only applicable to parameters and headers for responses. This makes sense, assuming we don't want to support csv-type parameters inside models.

In that case, the json format for arrays is probably not relevant. The only use case I can think of is supporting GeoJSON which may require an array in the format [1.0, 1.0]. However, I think we currently have other issues with supporting GeoJSON.

It looks like we also won't allow nested arrays in non-model arrays. We simply can't represent nested arrays using csv and most other options. The only way to support nested arrays (other than json arrays) is by using multi and each multi value can be a csv value. ?foo=1,2,3&foo=4,5,6 would theoretically translate to [ [1, 2, 3], [4, 5, 6] ]. This is very complicated to describe though. As such, we should probably drop support for nested arrays in non-model arrays altogether.

As for the default value, I'd actually go with csv rather than multi. multi makes sense in query parameters. I don't know if it makes sense in header and formData parameters. It definitely doesn't make sense in path parameters. And for the sake of path parameters, csv should be the default. This is also the expected representation of the original allowMultiple keyword from 1.2.

As for the brackets usage in the name, I've also only seen it used only in multi syntax. I'm just saying the multi value shouldn't imply the brackets in the name but rather they should come explicitly as the parameter name in the definition of the parameter.

[webron]

This was implemented without the default/json. The default value was set as csv.