Linter rulesAsyncAPIschema-constraints

schema-constraints

Since 0.9.0

This rule ensures that schema objects define constraints restricting the size of the underlying data.

Rule Details

Defining constraints enhances the robustness and reliability of the API’s structure, and protects consumers from unexpectedly large messages.

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.

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

When Not to Use It

If your API does not require specific constraints on its schema objects, you may not need to use this rule.

Compatibility

This rule is compatible with AsyncAPI 3.x documents. AsyncAPI 2.x documents are rejected by the reader and are not linted.

Related rules