-
Notifications
You must be signed in to change notification settings - Fork 9.1k
Parameter style definitions inconsistent with the examples #1945
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
There are other ambiguities too, like whether 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 |
From a quick review, I think I'm not going to try and defend 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 Encoding is also a problem. For |
I also find this confusing. @darrelmiller is it going to be fixed? |
Hi! I think it would at least make sense to say that This should also require updating the way the default value of
|
This was actually fixed some time ago for 3.0.4 and 3.1.1 - I'm not sure what PR it was but |
The style values table has a
type
column which I assume indicates which data types can be serialized using that style (e.g. adeepObject
style on a query parameter for any data type other thanobject
would constitute an invalid spec), in the same way that I assume thein
column determines which locations each style is valid in.But this is not consistent with the examples, and further brings up some curiosities:
simple
parameter style only supports arrays, yet it is the default style for path parameters and the only style for header parameters.simple
—that contradicts this by defining a schema with data typestring
.pipeDelimited
andspaceDelimited
both offer examples of serialized objects, not just arrays, and thesimple
style 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.The text was updated successfully, but these errors were encountered: