Are Style Examples correct for arrays and objects

[charjr]

Referring to the style examples section (identical on both 3.0.3 and 3.1.0):

I notice that some of the styles do not use the key "color" at all. For example:

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

For object with explode: true the word color is not found within ;R=100;G=200;B=150

Is this correct? If so, how does it maintain association with the object: color?

I may be wrong but I would expect something like this: ;color=R,100;color=G,200;color=B,150.

Any enlightenment on this would be greatly appreciated.
If it turns out there are any mistakes I'd be happy to put in a PR to update it.

[handrews]

@karenetheridge did one of your PRs fix this for the next patch release?

[karenetheridge]

The examples are correct. For those cases where "color" does not appear in the serialized form, the implication is that the parameter is meant to capture all of the values, and its name is arbitrary because it does not appear in the serialized string.

Therefore, given this openapi parameter specification:

name: color
in: query
explode: true
style: matrix
schema:
  type: object

..and this parameter string: ;R=100;G=200;B=150, the deserialized data for color would be:

{ "R": "100", "G": "200", "B": "150" }

and given this parameter string: ;foo=bar;bloop=yay;hello=goodbye, the deserialized data for color would be:

{ "foo": "bar", "bloop": "yay", "hello": "goodbye" }

This is also the solution for the sometimes-asked question "is there a way of capturing all query parameters into one openapi schema parameter [for example to describe dependencies between then]", e.g. asked here: #256

[charjr]

@karenetheridge Thank you for the example, that is really helpful!

I'm working on part of a library for validating requests against an OpenAPI. So I'm trying to work out all the weird, wonderful and horrible edge cases can be concocted in a query string.

I'm still unsure of what would happen for unusual edge cases such as two query parameters like this:

parameters:
  - name: color
    in: query
    explode: true
    style: matrix
    schema:
      type: object
  - name: paint
    in: query
    explode: true
    style: matrix
    schema:
      type: object

Because now I'm imagining strings like this: ;R=100;G=200;B=150&type=watercolour;viscosity=0.1.

Is that a correct example (i.e. could this actually happen)? If so, is there a set way to interpret that data or is it up to the tooling to decide?

[karenetheridge]

I think that would be a parsing error, because of the presence of &type=, but I haven't yet added the matrix style to my implementation yet so I cannot test :)

[charjr]

That is where I'm at a loss: From my understanding, though rather nonsensical, this is technically valid:

parameters:
  - name: color
    in: query
    explode: true
    style: matrix
    schema:
      type: object
  - name: paint
    in: query
    explode: true
    style: matrix
    schema:
      type: object

But I do not know how one would form a valid query string for it, especially if I were to specify required: true on both.

Can anyone specify what a valid query string would look like in this instance?

[darrelmiller]

@charjr The intent of the style and explode in an OpenAPI parameter is to map to the equivalent concepts in the URI Template specification https://www.rfc-editor.org/rfc/rfc6570 The best way to resolve URLs is to create an equivalent URI template from the OpenAPI parameter definition and then use a standard URI Template library to do the URL creation.

Your specific example is not valid because matrix style is only allowed for path parameters, not query parameters. Assuming you change to your example to path parameters the URI template would be

https://example.org/foo{;color,paint*}

Now, you can feed this into any standard URI Template library to see what the results should be.

[charjr]

@karenetheridge @darrelmiller Thank you, I think that has cleared it up for me a bit. And thank you for the resources to look into. I will close this now as my question has been answered.