Clarification on support for application/json encoded object properties in application/x-www-form-urlencoded messages

[LGraber]

I have been trying to read the spec and understand this to understand if some tools are "broken" or if the spec is just ... unclear (or I am reading it wrong). I need to support an application/x-www-form-urlencoded message where some properties are application/json encoded objects. From what I can read in the spec, this should be the expected, default serialization. The section on Encoding Object says: "The Content-Type for encoding a specific property. Default value depends on the property type: for object - application/json; ". I will say that I am very confused by that line when reading the section on "explode":

When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When style is form, the default value is true. For all other styles, the default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.

That doesn't make sense to me since if I want my property to simply be a json string, then I need to set it to explode: false but then it ignores contentType so ... I guess I have to assume it is application/json but then what would be the point of this parameter.

So, could someone tell me how to make the system accept a application/x-www-form-urlencoded message where one of the properties is a json encoded object. I attached a sample spec I created which I tested in Postman and SwaggerUI and they behave differently. I also tried with a codegen tool to see what they did and it was different also. I want to know what is "right" and then maybe I can fix something :)

Thanks
NestedOpenAPISpec.yml.txt

[LGraber]

To add, Postman always does comma delimted for the explode:false and explode:false, contentType:application/json. SwaggerUI on the other hand, also does json for the property value. It feels like I should be able to have either by using contentType attribute and it seems like the default should be application/json and not csv??

[handrews]

@LGraber

I agree that this is not very clear. My reading is that this is the key part:

If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.

This tells me that the text around defaults is a bit incomplete. An explicit explode: false causes the contentType to be ignored, but omitting explode entirely allows contentType to take effect.

This is shown by the example, which has a JSON object for address without any entry in the Encoding Object, and includes the comment # default is application/json on that address field. So that means that the value should be JSON text, without any further transformation or encoding (beyond what the multipart/form-data or application/x-www-form-urlencoded format requires, which is separate from the Encoding Object).

This is further supported by the Support for x-www-form-urlencoded Request Bodies, which uses a similar address example and states:

In this example, the contents in the requestBody MUST be stringified per [RFC1866] when passed to the server. In addition, the address field complex object will be stringified.

I think we should show the result of applying those examples (and probably clean up that text in the field table as well).

The confusion seems to have been introduced in OAS 3.1, as the text in 3.0.3 does not say anything about interactions with contentType and restricts it to just application/x-www-form-urlencoded.

[handrews]

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