Linter rulesSwagger 2.0schema-format-type-mismatch

schema-format-type-mismatch

Since 0.9.0 · fixed by --fix

This rule ensures that the format of an object is one that applies to its type.

Rule Details

Each well-known format applies to a single type. A format paired with another type (e.g. type: integer with format: date-time) is contradictory, and tools interpret it inconsistently.

The schema-format-type-mismatch rule checks every object of a Swagger 2.0 document that has a format: schemas, non-body parameters, response headers and items objects (objects with a $ref are checked where they are defined). It checks the formats Swagger 2.0 defines and the JSON Schema ones it allows, with the JSON types the OpenAPI format registry gives them, and the formats of openapi.custom_formats in the configuration file:

  • int32, int64 - integer or number, and string for int64,
  • float, double - number,
  • byte, binary, date, date-time, password, email, hostname, ipv4, ipv6, uri, uuid - string.

For these formats, it reports Schema type and format do not match when the object has another type or no type at all. Other formats are left to schema-format-unknown.

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:
    swagger:
      rules:
        schema-format-type-mismatch:
          - error
          - fixTypeFromFormat: false

Examples

Good.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  Pet:
    type: object
    properties:
      id:
        type: string
        format: uuid
      born_at:
        type: string
        format: date-time
      weight:
        type: number
        format: float

Bad.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  Pet:
    type: object
    properties:
      id:
        type: integer
        format: uuid
      born_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 object to the type the format applies to. In the “Bad” example above, both properties get type: string.

When Not to Use It

You may disable this rule if your API uses well-known format names with a different meaning.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading