Update Style Values and Style Examples for consistency

[charjr]

What I Thought I Understood

Looking at Style Values what I grasp is this:

• simple, spaceDelimited and pipeDelimited MUST be an array
• deepObject MUST be an object
• every other style can be a primitive, array or object

style	type	in	Comments
matrix	primitive, array, object	path	Path-style parameters defined by RFC6570
label	primitive, array, object	path	Label style parameters defined by RFC6570
form	primitive, array, object	query, cookie	Form style parameters defined by RFC6570. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple	array	path, header	Simple style parameters defined by RFC6570. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited	array	query	Space separated array values. This option replaces collectionFormat equal to ssv from OpenAPI 2.0.
pipeDelimited	array	query	Pipe separated array values. This option replaces collectionFormat equal to pipes from OpenAPI 2.0.
deepObject	object	query	Provides a simple way of rendering nested objects using form parameters.

What I Expect

What I expect to see when I look at Style Examples is this:

style	explode	empty	string	array	object
matrix	false	;color	;color=blue	;color=blue,black,brown	;color=R,100,G,200,B,150
matrix	true	;color	;color=blue	;color=blue;color=black;color=brown	;R=100;G=200;B=150
label	false	.	.blue	.blue.black.brown	.R.100.G.200.B.150
label	true	.	.blue	.blue.black.brown	.R=100.G=200.B=150
form	false	color=	color=blue	color=blue,black,brown	color=R,100,G,200,B,150
form	true	color=	color=blue	color=blue&color=black&color=brown	R=100&G=200&B=150
simple	false	n/a	n/a	blue,black,brown	n/a
simple	true	n/a	n/a	blue,black,brown	n/a
spaceDelimited	false	n/a	n/a	blue%20black%20brown	n/a
pipeDelimited	false	n/a	n/a	blue|black|brown	n/a
deepObject	true	n/a	n/a	n/a	color[R]=100&color[G]=200&color[B]=150

What I See

What I actually find on Style Examples is this:

• simple can be primitive, array or object (which conflicts with what I read earlier)
• spaceDelimited and pipeDelimited can be array or object (which conflicts with what I read earlier)
• deepObject MUST be an object
• everything else can be primitive, array or object

style	explode	empty	string	array	object
matrix	false	;color	;color=blue	;color=blue,black,brown	;color=R,100,G,200,B,150
matrix	true	;color	;color=blue	;color=blue;color=black;color=brown	;R=100;G=200;B=150
label	false	.	.blue	.blue.black.brown	.R.100.G.200.B.150
label	true	.	.blue	.blue.black.brown	.R=100.G=200.B=150
form	false	color=	color=blue	color=blue,black,brown	color=R,100,G,200,B,150
form	true	color=	color=blue	color=blue&color=black&color=brown	R=100&G=200&B=150
simple	false	n/a	blue	blue,black,brown	R,100,G,200,B,150
simple	true	n/a	blue	blue,black,brown	R=100,G=200,B=150
spaceDelimited	false	n/a	n/a	blue%20black%20brown	R%20100%20G%20200%20B%20150
pipeDelimited	false	n/a	n/a	blue|black|brown	R|100|G|200|B|150
deepObject	true	n/a	n/a	n/a	color[R]=100&color[G]=200&color[B]=150

What I Think Needs Correcting

Please correct me if I'm wrong, but my expectation is this:

style	type	in	Comments
matrix	primitive, array, object	path	Path-style parameters defined by RFC6570
label	primitive, array, object	path	Label style parameters defined by RFC6570
form	primitive, array, object	query, cookie	Form style parameters defined by RFC6570. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple	primitive, array, object	path, header	Simple style parameters defined by RFC6570. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited	array, object	query	Space separated array values. This option replaces collectionFormat equal to ssv from OpenAPI 2.0.
pipeDelimited	array, object	query	Pipe separated array values. This option replaces collectionFormat equal to pipes from OpenAPI 2.0.
deepObject	object	query	Provides a simple way of rendering nested objects using form parameters.

If this is the case, please let me know and I will make a PR to close it.

[karenetheridge]

Please refer to the 3.1.1 specification in the v3.1.1-dev branch, as there have already been some corrections to this area of the specification.

It does appear that the table is incorrect for simple, at least -- primitive and object types are supported there, and it probably makes sense to allow primitives for spaceDelimited and pipeDelimited.

[mikekistler]

Why does it make sense to allow primitives for spaceDelimited and pipeDelimited? The description for these two styles is specific to arrays.

spaceDelimited: Space separated array values.
pipeDelimited: Pipe separated array values.

[karenetheridge]

I'm coming at it from the perspective of a request/response validation author, where we're taking data in a request or response and deserializing it into a data structure. From this angle, allowing more types means fewer places where the validation would error out because of the wrong type being specified in the schema, but indeed it doesn't add any value to allow it (the application might as well accept an array with a single value).

[karenetheridge]

Update: we discussed this PR at the TSC meeting today (#3672) and decided:

• the changes for simple are sensible - all of primitives, arrays and objects are possible and make sense, so the spec should reflect that
• regarding spaceDelimited and pipeDelimited, a primitive type is not useful here (when writing an api spec, if you're expecting a string why would you specify style: spaceDelimited? just use simple form).

Therefore -- @charjr: could you possibly revert the changes to spaceDelimited and pipeDelimited in your PRs? I think then we should be able to review and merge them quickly (e.g. before or by the next TSC meeting). thanks!

[charjr]

@karenetheridge I've updated each PR to remove the primitive type from spaceDelimited and pipeDelimited.

Hopefully it's ready to go, if not let me know.

[karenetheridge]

looks great, thank you!

[karenetheridge]

I've added comments/suggestions to all 3 PRs following the discussion at the meeting today.

[charjr]

@karenetheridge updated, let me know if it needs any further changes.

[handrews]

All of these PRs were merged so I'm assuming this is resolved. Closing.