Schema defines 'additionalProperties' as a boolean value
Issue ID: warning-schema-additionalproperties-boolean
Description
The schema defines additionalProperties
as a Boolean value.
The reason additionalProperties
takes a boolean value comes from the role the attribute plays in JSON schemas. In JSON, by default, any object can also accept additional properties that are not defined in its schema as long as the properties defined in the schema are present. To change this behavior and stop allowing any additional properties to those explicitly defined in the schema, you can set additionalProperties
to false
.
OpenAPI Specification (OAS) v2 does not define this behavior, and the current tooling (such as parsers and codegen) does not support it. Instead, they only accept the value object
for this property. OAS v2 does also support using additionalProperties
to specify a schema to which the additional properties must conform.
Because boolean in additionalProperties
is not a documented part of the OAS, the API implementation may not behave according to developer expectations. Such a discrepancy has an inherent risk and is not recommended.
For more details, see the OpenAPI Specification.
Example
The following is an example of how this type of risk could look in your API definition. Here, additionalProperties
is set to false
. This behavior is supported in regular JSON but not in OAS v2:
{
"post": {
"operationId": "addPet",
"parameters": [
{
"name": "pet",
"in": "body",
"description": "Pet to add to the store",
"required": true,
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
]
}
}
Remediation
The safest option is not to allow additional properties. If the schema does not use allOf
at all, make sure you define all properties of the accepted JSON payload in the schema itself.
Do not use combining operations (allOf
) for defining additional properties in API definitions following the OAS v2.
We recommend updating your API definition to follow the OAS v3, because it offers proper support for additionalProperties
as Boolean, in addition to other improvements.
If you cannot update your API to OAS v3, use additionalProperties
to provide the schema that you want to support:
{
"post": {
"operationId": "addPet",
"parameters": [
{
"name": "pet",
"in": "body",
"description": "Pet to add to the store",
"required": true,
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": {
"schema": {
"$ref": "#/definitions/PetDetails"
}
}
}
}
]
}
}