Description
In OpenAPI 3.0, allowEmptyValue is valid only for query parameters and does not apply where the selected style cannot serialize the value. The specification discourages this property. Setting it does not mean every parameter accepts an empty value.
Potential impact
- API consumers may incorrectly assume that an empty value is allowed.
- Different documented and implemented input rules can cause failed requests or misleading tests.
Remediation
Remove allowEmptyValue from parameters where it does not apply, including path parameters. Distinguish empty values from omitted parameters, define the intended policy, and align it with the value schema and serialization. Check actual handling through client requests and server validation.
Examples
These examples describe an integer path parameter named id. It is outside the scope of allowEmptyValue.
Before
{
"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 version",
"required": true,
"allowEmptyValue": true,
"schema": {
"type": "integer"
}
}
]
}
}
}
After
{
"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": [
{
"in": "path",
"style": "label",
"description": "ID of the API version",
"required": true,
"schema": {
"type": "integer"
},
"name": "id"
}
]
}
}
}
The revised example removes allowEmptyValue from the path parameter. style: label specifies path serialization; it does not permit an empty integer value.