Linter rulesOpenAPIschema-format-defined

schema-format-defined

Since 0.0.1

This rule ensures that every schema object that is a string or a number has its format defined.

Rule Details

Defining the format of a string or numeric schema objects enhances the readability and understanding of the API’s structure.

The schema-format-defined rule is designed to ensure that all schema objects whose type is number or integer have also a format property defined: an integer format of the OpenAPI format registry (int8 to uint64, int32, int64, double-int, sf-integer) or unixtime for integer, a number format (float, double, decimal, …) for number, or a format of openapi.custom_formats of the matching type.

Configuration

None.

Examples

Good. Now it is obvious that birthDate is a ISO8601 date string.

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

Bad. It is not immediately obvious how birthDate is formated. Is it YYYY-MM-DD or DD-MM-YY, or perhaps YY/MM/DD ?

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

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.

Related rules