Should style: form examples include ? prefix? If so, what about spaceDelimited, pipeDelimited, and deepObject?

[handrews]

The examples for the simple, label, and matrix styles exactly match the corresponding RFC6570 output, including the initial ; for matrix or . for label.

RFC6570 form expansion includes the ? initial character, for the same reasons as the initial ; and . for matrix and label. In PR #3818 I note that that has implications for how multiple form parameters are translated to a form that could be assed to an RFC6570 implementation.

But the example table for form does not show the ? character, which seems incorrect to me. In issue #1945 (comment), @darrelmiller notes:

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

This implies to me that the ? should be present. However that also raises some questions:

1. Would example/examples in each Parameter Object each have the ? prefix, even though in a full query string only one of them will be next to it? Note that this does not mean that the others would use RFC6570's & operator, which I explained in more detail in PR Appendix on RFC6570-derived behavior + allowReserved (3.0.4) #3818
2. How does that fit with having to manually work around RFC6570's lack of support for form: style, allowReserved: true? (See also Appendix on RFC6570-derived behavior + allowReserved (3.0.4) #3818 (comment))
3. spaceDelimited and pipeDelimited are like style: form, explode: false, but with , replaced by space or |, so should their examples also show the ?
4. likewise, deepObject is like style: form, explode: true but with more complex names, so should it also show the ?

[handrews]

Oh and this has implications for the use of style: form with in: cookie because it the ? is always present then it never produces a correct value for the cookie:

• Warnings for header and cookie serialization (3.0.4) #3841

[karenetheridge]

I think we should be consistent with our examples -- and for the case of query parameters, it might be helpful to show examples as full URIs (including url encoding), to show how each query parameter is parsed out of the URI based on the style, explode, encoding etc configuration values.

[handrews]

Fix added to PR #3859, with ? included as that is most consistent with how label, matrix, and (trivially) simple are formatted. And @karenetheridge 's comment on consistency got two thumbs up, with no one else commenting.

@karenetheridge , it would be great to have more examples but rather than expanding the difficult-to-update spec, let's do that on the Learn site. Or at least, let's discuss it here where @jeremyfiel has also suggested something similar, and I have proposed addressing it on the learn site:

• Discussion Examples in a cURL-like format, preferably at the PathItem Object #3874

I'm going to keep this issue's scope limited to just the "should there be a ? or not?" question.

[handrews]

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!