OpenAPI-Specification
OpenAPI-Specification copied to clipboard
Parameter style definitions inconsistent with the examples
The style values table has a type column which I assume indicates which data types can be serialized using that style (e.g. a deepObject style on a query parameter for any data type other than object would constitute an invalid spec), in the same way that I assume the in column determines which locations each style is valid in.
But this is not consistent with the examples, and further brings up some curiosities:
- The
simpleparameter style only supports arrays, yet it is the default style for path parameters and the only style for header parameters.- Is this supposed to mean header parameters are only ever allowed to be arrays? No primitives can ever be passed to a header parameter?
- There is an example path parameter object that uses the default style—
simple—that contradicts this by defining a schema with data typestring.
- In the style examples table
pipeDelimitedandspaceDelimitedboth offer examples of serialized objects, not just arrays, and thesimplestyle has examples of an object as well as a string primitive.
These contradictions imply that my initial assumption about the type column in the style values table is incorrect. But there is no explanation about what it is supposed to indicate, then.
There are other ambiguities too, like whether explode: true is allowed for pipeDelimited and spaceDelimited parameters (and what that would look like), and the same regarding explode: false for deepObject.
My question is essentially: are the examples in the parameters section of the specification normative?
If the examples section is non-normative (which you would usually expect from a standard), then it is at least inconsistent, but would also imply that the type column of the style values table is the source of truth, and I just have a hard time believing that simple-style parameters were intended to only ever be arrays.
From a quick review, I think Simple should support primitive and object, as shown in the examples. I don't know why it was limited to arrays. I'll get that fixed.
I'm not going to try and defend deepObject. There was a strong desire from community members to support this, but there is no standard, so we allowed specifying it but the exact syntax would have to be communicated between API consumer and provider in some other way.
pipeDelimited and spaceDelimited were carry overs from OpenAPI v2 and don't fit naturally in the RFC6570 model. I'm on the fence as to whether we should just drop the object examples or expand the potential usage.
The examples were created primarily around what would a URI Template library do with the values. The examples should be consistent with the style constraints and I'm a little surprised that it has gone this long without someone point out how badly I screwed up there.
Thank you for taking the time to point out these inconsistencies. I will fix the obvious ones. I'm curious to your opinion on whether we should support space and pipe delimited objects. I'm tending towards no.
My opinion about pipe- and spaceDelimited is the same as yours; I don't think we should support them. The final parsed result is the same regardless of which serialization style you use, so I prefer less options because it simplifies clients and also simplifies the standard.
Encoding is also a problem. For pipeDelimited it's probably safe to assume that you would just percent-encode any pipe characters within the arguments, but what about spaces within arguments for spaceDelimited parameters? The standard doesn't mention what to do in that case, so a client won't know how to serialize it unless the parameter description happens to explain how to escape spaces.
I also find this confusing. @darrelmiller is it going to be fixed?
Hi! I think it would at least make sense to say that deepObject is not supported when explode=false.
This should also require updating the way the default value of explode is defined:
When style is either
formordeepObject, the default value istrue. For all other styles, the default value isfalse.
This was actually fixed some time ago for 3.0.4 and 3.1.1 - I'm not sure what PR it was but simple shows primitive, array, object and both pipeDelimited and spaceDelimited show array, object. Since the example table always showed these, the lack of the correct types in the style table was an accidental omission, and can be fixed without breaking compatibility. The patch releases should be out within the next couple of months.