schema-no-additional-properties

Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at error, Strict at error, All at error

This rule ensures that object schemas do not accept arbitrary additional properties.

Rule details

An object schema accepts properties that are not listed in properties unless additionalProperties is false. Open objects hide typos in property names, and let undocumented data pass through the API.

The schema-no-additional-properties rule checks every schema of a Swagger 2.0 document with type: object (schemas with a $ref are checked where they are defined). It reports Object schema does not disable additional properties when additionalProperties is absent or true.

A schema value of additionalProperties describes a map whose values have that schema. This is a deliberate choice, and such schemas are not reported.

The OpenAPI linter has a rule of the same name, schema-no-additional-properties, for OpenAPI 3.x documents.

Turn the rule off if your API deliberately accepts or returns properties that are not described, for example to stay compatible with future versions.

Examples

Good. Pet is closed, and Labels is a map of strings.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  Pet:
    type: object
    additionalProperties: false
    properties:
      name:
        type: string
      labels:
        $ref: '#/definitions/Labels'
  Labels:
    type: object
    additionalProperties:
      type: string

Bad. Both Pet and its owner property accept any additional property.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  Pet:
    type: object
    properties:
      name:
        type: string
      owner:
        type: object
        additionalProperties: true
        properties:
          name:
            type: string

Automatic fixes

--fix sets additionalProperties: false on every reported schema.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        schema-no-additional-properties: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?