Description
In OpenAPI 3.0, a Parameter Object’s allowReserved describes whether query values may contain reserved characters without percent-encoding. It does not apply to path, header or cookie parameters.
Potential impact
- API consumers may misunderstand how path values must be encoded.
- Different interpretations of reserved characters can change the received value or target path.
Remediation
Use Parameter Object allowReserved only for query parameters. Remove it from other locations and define the actual encoding rules. Do not move a parameter merely to make this property applicable; check that the API path and client requests agree.
Examples
These excerpts compare the id path parameters. The response definition for /users/{id} is omitted.
Before
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/{id}": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the API the version",
"required": true,
"allowReserved": true,
"schema": {
"type": "integer"
}
}
]
},
"/users/{id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"allowReserved": true,
"description": "The user ID",
"schema": {
"type": "integer",
"minimum": 1
}
}
]
}
}
}
}
After
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/{id}": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the API the version",
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/users/{id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The user ID",
"schema": {
"type": "integer",
"minimum": 1
}
}
]
}
}
}
}
The revised example keeps the path parameters and removes their inapplicable allowReserved properties. Path values still need to follow the actual URI encoding rules.