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"
                            
                        }
                    }
                }
            }
        ]
    }
}