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

rfc6570 template clarification requested for the parameter styles, cookie use case unclear #2940

Closed
spacether opened this issue Jun 9, 2022 · 7 comments
Assignees
Labels
clarification requests to clarify, but not change, part of the spec param serialization Issues related to parameter and/or header serialization
Milestone

Comments

@spacether
Copy link

spacether commented Jun 9, 2022

Hello there. Can we get some clarification on:

  • cookie parameter example values using form serialization
  • rfc6570 template clarification for all style and parameter type combos?

I am asking because the swagger docs show examples:
https://swagger.io/docs/specification/serialization/
And in the query parameter examples we see:

style explode rfc6570 template array_value
form true {?id*} ?id=3&id=4&id=5
form false {?id} ?id=3,4,5

Yet for cookie parameters values lack the ? prefix.
This is not consistent with the examples given in rcf6570 for form style {?var} or {&var} expansion
Those expansions require the ? or & prefix with values like:
{?var} -> {?id} ->
{?id*} ?id=3&id=4&id=5
{?id} -> ?id=3,4,5

{&var} -> {&id} ->
{&var*} &id=3&id=4&id=5
{&var} &id=3,4,5
If we are meant to exclude those prefixes, and use form styles please provide the uri templates and direction.

The openapi spec omits the ? prefix from the form examples of serialized data though they are needed in style form query parameter serialization.

Header Question:

Also, what should None serialize to in a header? In a path it is empty string. In a header should the value be empty string or should it be omitted?

Related issues:

@spacether spacether changed the title Cookie parameter form clarification + rfc6570 uri template clarification for the styles Cookie parameter form clarification + rfc6570 uri template clarification for the styles requested Jun 9, 2022
@spacether spacether changed the title Cookie parameter form clarification + rfc6570 uri template clarification for the styles requested rfc6570 template clarification requested for the parameter styles, cookie use case unclear Jun 9, 2022
@MaceWindu
Copy link

MaceWindu commented Oct 31, 2022

explode=false doesn't even make sense for cookies, as it introduce comma, not allowed by cookie value. Still, it is included into cookie examples here https://swagger.io/docs/specification/serialization/ ...

@handrews
Copy link
Member

@spacether OAS 3.x does not use RFC 6570 URI Template syntax. That Swagger documentation is just saying that certain RFC 6570 template syntaxes are equivalent to certain style and explode combinations.

@spacether
Copy link
Author

spacether commented Jan 27, 2024

If they are identical in implementation, openapi gives no specific step by step directions on how to serialized the data and rfc 6570 is mentioned then it looks to me like the spec does use it. If so can the spec specifically mention that sterilization uses the rfc 6570?

If they do not use it and serialization does not conform to the rfc, can that be mentioned and can direction on how to serialize/or the rfc that is being used be linked to?

@handrews
Copy link
Member

@spacether the specification already cites the parts of RFC 6570 that is uses, in the places where it is used. This usage is not the full RFC 6570 syntax. OAS URL Templating syntax is defined in the OAS itself.

There's a limit to how much the spec can and should talk about what RFCs it doesn't use. But I'll leave this open (I don't think I actually meant to close it - sorry, was closing a lot of issues and probably hit it on autopilot) and tag it as a clarification to consider for patch releases.

@handrews handrews reopened this Jan 27, 2024
@handrews handrews added clarification requests to clarify, but not change, part of the spec param serialization Issues related to parameter and/or header serialization labels Jan 27, 2024
@handrews
Copy link
Member

@spacether I have finally had time to dig into this in depth, and agree that there are aspects of the correlation with RFC 6570 that are not clear (see also issue #3759, for example). I'm gathering up parameter serialization clarification requests for the patch releases so I'll throw this on the pile.

@handrews handrews self-assigned this Apr 28, 2024
@handrews handrews added this to the v3.0.4 milestone Apr 28, 2024
@spacether
Copy link
Author

Thanks!

@handrews
Copy link
Member

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!
This is addressed in the new Appendices C and D, as well as by making the table of style examples more comprehensive.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
clarification requests to clarify, but not change, part of the spec param serialization Issues related to parameter and/or header serialization
Projects
None yet
Development

No branches or pull requests

3 participants