Description
In OpenAPI 3.0, encoding.allowReserved applies to application/x-www-form-urlencoded request bodies. It cannot specify reserved-character encoding for other media types.
Potential impact
- API consumers may incorrectly assume that reserved characters can be sent unchanged.
- Different client and server interpretations of encoding can alter the received value.
Remediation
Use encoding.allowReserved only for application/x-www-form-urlencoded bodies. Remove it for other formats and follow their encoding rules. If changing the media type, update the API and clients together and verify how reserved characters are handled.
Examples
These excerpts define the NewItem request body. Its operation reference 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",
"allowReserved": true
}
}
}
}
}
}
}
}
After
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": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "binary"
}
}
},
"examples": {
"tshirt": {
"$ref": "#/components/examples/tshirt"
}
},
"encoding": {
"code": {
"contentType": "image/png, image/jpeg",
"allowReserved": true
}
}
}
}
}
}
}
}
The revised example uses a URL-encoded form, where allowReserved applies. This differs from multipart file upload, so confirm that the actual API supports the format instead of changing only the document.