Linter rulesOpenAPIschema-format-type-mismatch

schema-format-type-mismatch

Since 0.0.1 · fixed by --fix

This rule checks all schema objects and warns if any of them have their type and format properties contradicting each other.

Rule Details

Contradicting type and format properties can lead to confusion and misinterpretation of the API’s structure.

The schema-format-type-mismatch rule is designed to ensure that all schema objects have their type and format properties in agreement. It reports a schema whose format is in the OpenAPI format registry when none of the schema’s types is a JSON type of that format (see Formats for the list). For example:

  • date, uuid, email, http-date, language and the other string formats need type: string;
  • int8 to uint64, int32, int64, double-int and sf-integer need type: integer or type: number;
  • float, double and sf-decimal need type: number (not integer);
  • int64 and uint64 also allow type: string, and decimal and decimal128 allow string and number, as the registry does;
  • unixtime allows integer, number and string.

The formats of openapi.custom_formats in the configuration file are checked against the type given there, and override the registry’s.

A schema without a type is reported too. Formats neither in the registry nor custom are left to schema-format-unknown.

Configuration

The optional fixTypeFromFormat boolean controls whether --fix replaces a mismatched schema type with the recognized format’s type. It defaults to true.

Examples

Good.

components:
  schemas:
    User:
      type: object
      properties:
        birthDate:
          type: string
          format: date

Bad.

components:
  schemas:
    User:
      type: object
      properties:
        birthDate:
          type: integer
          format: date

When Not to Use It

We recommend to always enable this rule.

Automatic fixes

When invoked with --fix, the schema gets the singleton type of its format: integer formats set integer, decimal and decimal128 set string, the other number formats set number and string formats set string. Unknown formats remain manual.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.

Related rules

Further reading