Review Encoding Object explode applicability

Description

In OpenAPI 3.0, encoding.explode describes how array or object values are serialized in an application/x-www-form-urlencoded request body. It does not apply to other media types and has no effect on values such as strings that are neither arrays nor objects.

Potential impact

API consumers may misunderstand how array or object fields are sent.
Serialization that differs from the server’s expectations can omit values or cause requests to fail.

Remediation

Set encoding.explode according to the array or object serialization needed in an application/x-www-form-urlencoded body. Remove it for other media types and follow their rules. If changing the media type, confirm support on both the client and server and test actual requests.

Examples

These excerpts define the NewItem request body. The operation using it and the tshirt example definition are omitted.

Before

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 response",
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "links": [
                            {
                              "href": "http://127.0.0.1:8774/v2/",
                              "rel": "self"
                            }
                          ],
                          "status": "CURRENT",
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "requestBodies": {
      "NewItem": {
        "description": "Item data",
        "required": true,
        "content": {
          "multipart/form-data": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "examples": {
              "tshirt": {
                "$ref": "#/components/examples/tshirt"
              }
            },
            "encoding": {
              "code": {
                "contentType": "image/png, image/jpeg",
                "explode": true
              }
            }
          }
        }
      }
    }
  }
}

After