schema-constraints

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

This rule ensures that schema objects 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 message: the consumer that stores them is the first to find out. Bounds in the document are checked by validators, and generated code picks the right types.

The schema-constraints rule checks every schema of an AsyncAPI document (component schemas, message payloads and headers, parameter schemas, and all schemas nested in them) and requires, depending on the schema type:

  • integers - both a lower bound (minimum or exclusiveMinimum) and an upper bound (maximum or exclusiveMaximum),
  • numbers - both a lower bound and an upper bound, as for integers,
  • strings - maxLength, pattern, format or enum,
  • arrays - maxItems,
  • objects - maxProperties, or additionalProperties: false.

A schema with several types (e.g. type: [string, integer]) is checked for each of them. The reported messages are Integer schema does not define constraints restricting its range, Numeric schema does not define constraints restricting its range, String schema does not define constraints restricting its length, Array schema does not define constraints restricting its size and Object schema does not define constraints restricting its size.

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

Configuration

The configuration should be an object whose keys are supported schema types, and values are boolean values. Only the types set to true are checked, and at least one schema type must be set to true.

Supported schema types are integer, number, string, array and object.

By default, constraints for all supported schema types are verified. The recommended ruleset checks only number and string schemas.

Configuration example. The rule with the following configuration checks only array and object schemas, and does not check numbers and strings.

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

Examples

Good.

asyncapi: 3.0.0
info:
  title: User Events
  version: 1.0.0
components:
  schemas:
    User:
      type: object
      properties:
        username:
          type: string
          maxLength: 20
          pattern: "^[a-z0-9_-]{3,16}$"
        roles:
          type: array
          items:
            type: string
            enum: [admin, member]
          maxItems: 5
        age:
          type: integer
          minimum: 18
          maximum: 100
      maxProperties: 3

Bad.

asyncapi: 3.0.0
info:
  title: User Events
  version: 1.0.0
components:
  schemas:
    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.asyncapi has the details.

commands:
  lint:
    asyncapi:
      rules:
        schema-constraints: off

Related rules

Last updated on View as Markdown
Was this helpful?