schema-constraints

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at warning

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

Rule details

A schema without bounds accepts a 2 GB string in a name and an array of a million items in a request: the server that stores them is the first to find out. Bounds in the document are checked by validators and mocks, and generated clients and servers pick the right types.

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.

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

Turn the rule off when the API does not bound the size of its values.

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

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-constraints: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?