Linter rulesAsyncAPIschema-format-type-mismatch

schema-format-type-mismatch

Since 0.9.0 · fixed by --fix

This rule ensures that the format of a schema is consistent with its type.

Rule Details

Formats apply to values of specific types. A schema such as type: integer, format: email is contradictory: validators ignore the format, and code generators produce unexpected types.

The schema-format-type-mismatch rule checks every schema of an AsyncAPI document whose format is in the OpenAPI format registry or in openapi.custom_formats of the configuration file, and reports Schema type and format do not match when none of the schema’s types is a JSON type of the format:

  • the integer formats (int8 to uint64, int32, int64, double-int, sf-integer) need integer or number, and int64 and uint64 also allow string;
  • float, double and sf-decimal need number;
  • decimal and decimal128 allow string and number, unixtime also integer;
  • the others (date, date-time, uuid, email, http-date, …) need string.

A schema with one of these formats but without a type is reported as well. Other formats are left to schema-format-unknown. The Formats page lists every format.

Configuration

The configuration block is an object with a single optional boolean property, fixTypeFromFormat, which controls whether reported issues can be fixed automatically (see “Automatic fixes”). The default value is true.

Configuration Example. The following configuration reports mismatches, but does not fix them.

version: "1.0"
commands:
  lint:
    asyncapi:
      rules:
        schema-format-type-mismatch:
          - error
          - fixTypeFromFormat: false

Examples

Good.

asyncapi: 3.0.0
info:
  title: User Events
  version: 1.0.0
components:
  schemas:
    UserSignedUp:
      type: object
      properties:
        email:
          type: string
          format: email
        signed_up_at:
          type: string
          format: date-time

Bad.

asyncapi: 3.0.0
info:
  title: User Events
  version: 1.0.0
components:
  schemas:
    UserSignedUp:
      type: object
      properties:
        email:
          type: integer
          format: email
        signed_up_at:
          format: date-time

Automatic fixes

When fixTypeFromFormat is true and the linter is invoked with the --fix option, this rule sets the type of every reported schema to the type the format applies to. In the “Bad” example above, both properties get type: string.

When Not to Use It

We recommend to always enable 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