Linter rulesSwagger 2.0schema-constraints

schema-constraints

Since 0.9.0

This rule ensures that typed objects of a Swagger 2.0 document define constraints restricting the size of the underlying data.

Rule Details

Defining constraints enhances the robustness and reliability of the API, and protects consumers and servers from unexpectedly large values.

The schema-constraints rule checks every object of the document that has a type: schemas (definitions, properties, items, allOf members, additionalProperties, body parameter and response schemas), non-body parameters, response headers and items objects. Objects with a $ref are skipped (their targets are checked where they are defined), and body parameters are checked through their schema. Depending on the type, the rule requires:

  • integer - both maximum and minimum; it reports Integer schema does not define constraints restricting its range,
  • number - both maximum and minimum; it reports Numeric schema does not define constraints restricting its range,
  • string - maxLength, pattern, format or enum; it reports String schema does not define constraints restricting its length,
  • array - maxItems; it reports Array schema does not define constraints restricting its size,
  • object - maxProperties or additionalProperties: false; it reports Object schema does not define constraints restricting its size. Only schemas are checked for this type.

Objects of type boolean or file, and schemas without a type, are not checked.

Configuration

The configuration is an object whose keys are the types integer, number, string, array and object, and whose values are booleans. Only the types set to true are checked, and at least one type must be set to true.

By default, all five types are checked. The recommended ruleset checks only number and string.

Configuration Example. The rule with the following configuration checks only arrays and objects.

version: "1.0"
commands:
  lint:
    swagger:
      rules:
        schema-constraints:
          - warning
          - array: true
            object: true

Examples

Good.

swagger: '2.0'
info:
  title: Users
  version: 1.0.0
paths:
  /users:
    get:
      parameters:
        - name: limit
          in: query
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Users
          schema:
            type: array
            maxItems: 100
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    additionalProperties: false
    properties:
      username:
        type: string
        pattern: "^[a-z0-9_-]{3,16}$"
      roles:
        type: array
        maxItems: 5
        items:
          type: string
          enum: [admin, member]
      age:
        type: integer
        minimum: 18
        maximum: 100

Bad. None of the typed objects is constrained.

swagger: '2.0'
info:
  title: Users
  version: 1.0.0
paths:
  /users:
    get:
      parameters:
        - name: limit
          in: query
          type: integer
      responses:
        '200':
          description: Users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      username:
        type: string
      roles:
        type: array
        items:
          type: string
      age:
        type: integer

When Not to Use It

If your API does not need to restrict the size of its values, you may not need to use this rule.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading