schema-format-unknown

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

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

Rule details

Validators, mock servers and code generators ignore formats they do not know, so a misspelled format (date_time, uuid4) stops being checked without a word. Formats your API defines on purpose are declared in the configuration file:

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

The rule is off in the recommended ruleset, since OpenAPI allows any format, and a warning in strict and all. See Formats for the registry’s formats. Turn the rule off when the document uses many formats of its own and listing them in the configuration file is not worth it.

Examples

Good. uuid is in the registry.

components:
  schemas:
    Id:
      type: string
      format: uuid

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

components:
  schemas:
    Id:
      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.rules has the details.

commands:
  lint:
    rules:
      schema-format-unknown: off

Related rules

Further reading

Was this helpful?