schema-format-type-mismatch

Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at error, Strict at error, All at error

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.

The OpenAPI linter has a rule of the same name, schema-format-type-mismatch, for OpenAPI 3.x documents.

Turn the rule off if your API uses well-known format names with a different meaning.

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.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        schema-format-type-mismatch: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?