schema-format-type-mismatch

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. The rule issues a warning for the following combinations of format and type fields:

• format is one of date, date-time, time, duration, email, idn-email, hostname, idn-hostname, ipv4, ipv6, uri, uri-reference, iri, iri-reference, uri-template, uuid, json-pointer, relative-json-pointer, regex or password, but type is not string
• format is one of int32 or int64, but type is not integer
• format is one of float or double, but type is not number

Configuration

None.

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.

Compatibility

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