schema-format-type-mismatch

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

This rule checks that the format of a schema fits its type: date on a string, int64 on an integer.

Rule details

A format that does not fit the type is a contradiction that every tool resolves its own way: a validator trusts the type and ignores the format, a generator may do the opposite, and a mock server generates data that the API cannot return. The rule 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

An object with one optional property, fixTypeFromFormat: whether --fix replaces a mismatched type with the type of the format. true by default.

Examples

Good. date is a string format.

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

Bad. An integer with a string format.

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

Automatic fixes

--fix gives the schema the 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 stay for you to resolve.

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.rules has the details.

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

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?