Description
OpenAPI 2.0 additionalProperties accepts a Boolean or a schema. false forbids undefined properties, true or omission allows them, and a schema constrains their values. Using a Boolean does not by itself make the specification invalid.
Potential impact
- A broader policy than intended may let an implementation accept unexpected data.
- Forbidding extension properties that clients need can reject otherwise legitimate requests.
Remediation
Choose additionalProperties according to the data contract. Retain false to forbid extra properties; to allow them, specify an appropriate value schema or use true. Check actual server-side input validation and avoid broadening the allowed data unnecessarily when editing the specification.
Examples
The first example forbids undefined properties in a response object. These examples compare different policies for additional properties.
Before
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
}
}
}
}
}
After
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": {
"$ref": "#/definitions/User"
}
}
}
}
}
}
},
"definitions": {
"User": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
]
}
}
}
The second example permits extra properties whose values conform to the User schema. Replacing false with a schema changes the contract and is not a required correction in every case.