schema-datetime-suffix (Swagger 2.0 linter rule)

schema-datetime-suffix

Since 0.9.0

This rule ensures that the names of date and date-time properties end with a common suffix.

Rule Details

A consistent suffix makes temporal properties easy to recognize, and distinguishes them from other properties describing the same concept (e.g. created_at versus created_by).

The schema-datetime-suffix rule checks the properties of every schema of a Swagger 2.0 document. For every property whose schema has the date or date-time format and whose name does not end with the configured suffix, it reports Property name <name> should end with <suffix>. A property defined with a $ref has the format of the referenced schema. The issue is reported at the property itself, not at a (possibly shared) referenced schema.

The default suffix is _at.

Configuration

The configuration block is a non-empty string: the required suffix.

Configuration Example. The following configuration requires temporal properties to end with At, which fits camelCase property names.

version: "1.0"
commands:
  lint:
    swagger:
      rules:
        schema-datetime-suffix: [warning, At]

Examples

Good. With the default configuration.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  Adoption:
    type: object
    properties:
      adopted_at:
        type: string
        format: date-time
      born_at:
        $ref: '#/definitions/Day'
  Day:
    type: string
    format: date

Bad. With the default configuration, both properties are reported.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  Adoption:
    type: object
    properties:
      adoption_date:
        type: string
        format: date-time
      birthday:
        $ref: '#/definitions/Day'
  Day:
    type: string
    format: date

When Not to Use It

You may disable this rule if your API follows a different convention for naming temporal properties.

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.