Encoding of request bodies as x-www-form-urlencoded, and handling of arrays/explode

[jdegre]

Hi,
A, hopefully, straightforward question on the correct interpretation of the OpenAPI spec.

Regarding the x-www-form-urlencoded encoding of request bodies, such as this example:

      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                foo:
                  type: array
                  items:
                    type: object
                    properties:
                      a:
                        type: integer
                      b:
                        type: integer

How is the foo array supposed to be encoded in the request body? As an exploded array?, such as:

foo={"a":1,"b":2}&foo={"a":3,"b":4}

or not exploded? such as:

foo={"a":1,"b":2},{"a":3,"b":4}

I'm aware that the explode behavior can be explicitly indicated by adding an encoding section with style: form and explode: true/false, but I cannot find in the OpenAPI spec a clear indication of what is the expected behavior when the encoding section is NOT provided.

Out of curiosity, I have tried with Swagger UI and it follows the non-exploded approach (2nd example), but please note that this is not a question about Swagger UI or any other tool. I'm interested in the correct interpretation of the OpenAPI spec.

Thanks in advance!

[webron]

@jdegre great question, and perhaps we need to provide a clearer explanation in the spec.

If you look at https://spec.openapis.org/oas/v3.0.3#support-for-x-www-form-urlencoded-request-bodies you'll see it says:

When passing complex objects in the application/x-www-form-urlencoded content type, the default serialization strategy of such properties is described in the Encoding Object’s style property as form.

So basically, if encoding isn't explicitly provided, it'll use the relevant default values provided in the Encoding Object. Hope this helps!

[jdegre]

Thanks @webron for the feedback!

I also noted the part of the spec you quoted, regarding the default values for the Encoding Object. And, yes, it would be good to clarify in the spec that those default values are to be applied when the entire Encoding Object is absent.

So, in the description of the Encoding Object, it is said that the default value of explode is true, when style is form.

Then, if that is the expected behavior, it seems that Swagger UI is not behaving according to the spec., right?, since it applies a explode: false encoding when no encoding is provided (but that would be a separate issue, to be opened in the relevant tooling repo).

[kerrykimbrough]

@jdegre Your example show an interesting case where a form-style property is a composite value (in your example, an array) that contains another composite value (in your example, an object). The OAS defines the effect of form style on arrays and objects, but it says nothing about how to serialize the interior composite values that they contain.

In your example, for the interior object values that are items of a form-style array, you show a JSON encoding. That is very surprising to me. I would never expect this to be the intention of OAS.

@webron Can you clarify the intention of OAS for the serialization of interior composite values?

[kerrykimbrough]

I now see that the question of interior value serialization is the subject of issue #1706

[handrews]

See PR #3719 for the clarification.

[handrews]

The PR has been merged for 3.0.4, and PRs porting the fix to 3.1.1 and 3.2.0 are open and expected to be merged, so I'm declaring this resolved.