AEP-0142 Linter Rules

Rules for AEP-142: Time and Duration

aep-142-time-field-type

Rule: Fields with time-related suffixes should use appropriate types and formats.

This rule enforces that fields with time-related suffixes use the correct OpenAPI types according to AEP-142.

Details

This rule validates fields based on their suffix:

Timestamp fields (_time):

Must have type: string
Must have format: date-time (RFC 3339)

Timestamp array fields (_times):

Must have type: array
Array items must have type: string and format: date-time (RFC 3339)

Date fields (_date):

Must have type: string
Must have format: date (ISO 8601)

Duration fields (_seconds, _millis, _micros, _nanos):

Must have type: integer or type: number

This ensures time-related fields conform to the proper formats and are correctly validated.

Examples

Incorrect code for this rule:

schemas:
  book:
    type: object
    properties:
      create_time:
        type: string
        # Missing format: date-time
      publish_times:
        type: array
        items:
          type: integer
          # Wrong item type - should be string with date-time format
      birth_date:
        type: integer
        # Wrong type - should be string with date format
      ttl_seconds:
        type: string
        # Wrong type - should be integer

Correct code for this rule:

schemas:
  book:
    type: object
    properties:
      create_time:
        type: string
        format: date-time
      publish_times:
        type: array
        items:
          type: string
          format: date-time
      birth_date:
        type: string
        format: date
      ttl_seconds:
        type: integer

Disabling

If you need to violate this rule for a specific field, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/components/schemas/book/properties/create_time'
    rules:
      aep-142-time-field-type: 'off'

aep-142-time-field-names

Rule: Timestamp fields should use imperative mood with _time suffix, not past tense.

This rule encourages consistent naming conventions for timestamp fields by discouraging past-tense field names.

Details

This rule complains if timestamp fields (those with type: string and format: date-time) use past-tense names like:

created, creation
updated, modified
deleted
published
started, ended, completed
expired, purged

Instead, use imperative mood with a _time suffix (e.g., create_time, update_time).

The rule uses “contains” matching, so it also catches compound names like last_modified, time_created, etc.

Examples

Incorrect code for this rule:

schemas:
  book:
    type: object
    properties:
      created:
        type: string
        format: date-time
      last_modified:
        type: string
        format: date-time

Correct code for this rule:

schemas:
  book:
    type: object
    properties:
      create_time:
        type: string
        format: date-time
      update_time:
        type: string
        format: date-time

Disabling

If you need to violate this rule for a specific field, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/components/schemas/book/properties/created'
    rules:
      aep-142-time-field-names: 'off'

aep-142-time-field-suffix

Rule: Scalar timestamp fields must end in _time suffix.

This rule enforces that scalar timestamp fields (those with type: string and format: date-time) end with the _time suffix, as specified in AEP-142.

Note: This rule only validates scalar fields. Array timestamp fields (which should use _times suffix) are validated by the aep-142-time-field-type rule.

Details

This rule checks all fields with format: date-time and ensures they end in _time. This helps maintain consistency across APIs and follows the AEP-142 requirement that timestamp fields should be named like create_time, update_time, etc.

Examples

Incorrect code for this rule:

schemas:
  book:
    type: object
    properties:
      expiration:
        type: string
        format: date-time
        # Missing _time suffix
      scheduled_at:
        type: string
        format: date-time
        # Missing _time suffix

Correct code for this rule:

schemas:
  book:
    type: object
    properties:
      expire_time:
        type: string
        format: date-time
      schedule_time:
        type: string
        format: date-time

Disabling

If you need to violate this rule for a specific field, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/components/schemas/book/properties/expiration'
    rules:
      aep-142-time-field-suffix: 'off'