schema-datetime-suffix

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

This rule checks that the name of every property with the date, date-time or time format ends with _at, or with the suffix configured.

Rule details

A reader of created_at knows it is a point in time without looking at the schema, and knows that created next to it is something else, a flag perhaps. One suffix for every date and time in the API makes the names say their type.

The rule looks at the properties of object schemas and reports Property name ... should end with ....

Configuration

A non-empty string: the suffix. _at by default. Pick the suffix that fits the naming convention of your properties: At for camel case (createdAt), _at for snake case.

Configuration example. Camel-case properties.

commands:
  lint:
    rules:
      schema-datetime-suffix:
        - warning
        - At

Examples

Good. With the default suffix.

components:
  schemas:
    User:
      type: object
      properties:
        created_at:
          type: string
          format: date-time

Bad. Nothing in the name says it is a date.

components:
  schemas:
    User:
      type: object
      properties:
        creation:
          type: string
          format: date-time

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-datetime-suffix: off
Was this helpful?