schema-format-unknown

Since 0.10.0 · In the rulesets: Strict at warning, All at warning

This rule reports a format of a Swagger 2.0 document which is neither in the OpenAPI format registry nor declared in openapi.custom_formats of the configuration file.

Rule details

Tools ignore formats they do not know, so a misspelled format (date_time, uuid4) stops being checked without a word. Formats defined on purpose are declared in the configuration file:

openapi:
  custom_formats:
    - {name: currency-code, type: string}

The rule is off in the recommended ruleset and a warning in strict and all. See Formats for the registry’s formats.

Turn the rule off when the documents use many formats of their own and listing them in the configuration file is not worth it.

Examples

Good. uuid is in the registry.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  PetId:
    type: string
    format: uuid

Bad. uuid4 is not, so nothing checks the value.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  PetId:
    type: string
    format: uuid4

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-unknown: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?