Linter rulesSwagger 2.0schema-format-defined

schema-format-defined

Since 0.9.0

This rule ensures that numeric objects declare the size of their values with a format.

Rule Details

The integer and number types do not say how large values may be or which precision they have. The formats int32, int64, float and double let consumers and code generators choose suitable native types.

The schema-format-defined rule checks every typed object of a Swagger 2.0 document: schemas, non-body parameters, response headers and items objects (objects with a $ref are checked where they are defined). It reports:

  • Schema with integer type does not define proper format for an integer object whose format is not int32 or int64,
  • Schema with number type does not define proper format for a number object whose format is not float or double.

Objects of other types are not checked.

Configuration

None.

Examples

Good.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths:
  /pets:
    get:
      parameters:
        - name: limit
          in: query
          type: integer
          format: int32
      responses:
        '200':
          description: Pets
definitions:
  Pet:
    type: object
    properties:
      id:
        type: integer
        format: int64
      weight:
        type: number
        format: double

Bad. The parameter has no format, and the properties have formats of other types.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths:
  /pets:
    get:
      parameters:
        - name: limit
          in: query
          type: integer
      responses:
        '200':
          description: Pets
definitions:
  Pet:
    type: object
    properties:
      id:
        type: integer
        format: uuid
      weight:
        type: number
        format: int32

When Not to Use It

You may disable this rule if the size of numeric values does not matter for your API.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading