Skip to content
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

Parameter style definitions inconsistent with the examples #1945

Closed
vvanpo opened this issue Jun 11, 2019 · 6 comments
Closed

Parameter style definitions inconsistent with the examples #1945

vvanpo opened this issue Jun 11, 2019 · 6 comments
Assignees
Labels
examples requests for more or better examples in the specification param serialization Issues related to parameter and/or header serialization
Milestone

Comments

@vvanpo
Copy link

vvanpo commented Jun 11, 2019

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 simple parameter 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 type string.
  • In the style examples table pipeDelimited and spaceDelimited both offer examples of serialized objects, not just arrays, and the simple 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.

@vvanpo
Copy link
Author

vvanpo commented Jun 11, 2019

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.

@darrelmiller
Copy link
Member

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.

@darrelmiller darrelmiller self-assigned this Jun 12, 2019
@vvanpo
Copy link
Author

vvanpo commented Jun 16, 2019

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.

@brozansk
Copy link

I also find this confusing. @darrelmiller is it going to be fixed?

@handrews handrews added examples requests for more or better examples in the specification param serialization Issues related to parameter and/or header serialization labels Jan 27, 2024
@iglosiggio
Copy link

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 form or deepObject, the default value is true. For all other styles, the default value is false.

@handrews
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
examples requests for more or better examples in the specification param serialization Issues related to parameter and/or header serialization
Projects
None yet
Development

No branches or pull requests

5 participants