schema-format-defined

Since 0.9.0 · In the rulesets: Recommended at error, Strict at error, All at error

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.

The OpenAPI linter has a rule of the same name, schema-format-defined, for OpenAPI 3.x documents.

Turn the rule off if the size of numeric values does not matter for your API.

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

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

Related rules

Further reading

Was this helpful?