IPA-121: Datetime

Datetime can be confusing as timezones and calendars come into play. To help clients understand how datetime is being used, its format should be uniform across the API platform.

Guidance

1. All timestamp values must use the ISO 8601 datetime format in UTC.

   components:
     schemas:
       Order:
         type: object
         properties:
           createdAt:
             type: string
             format: date-time
             description: Creation time of the order in ISO 8601 format and UTC.
             example: "2026-01-15T09:30:00Z"

   Why:

   The value is an ISO 8601 datetime with a Z offset, so every client reads the same instant regardless of local timezone, and format: date-time lets tooling parse it as a timestamp.

   components:
     schemas:
       Order:
         type: object
         properties:
           createdAt:
             type: string
             description: Creation time of the order.
             example: "01/15/2026 09:30 PST"

   Why:

   The value is a locale-specific string in a local timezone, so the same instant serializes differently across regions and cannot be parsed as a standard timestamp. A consumer cannot tell when the order was created without knowing the producer's calendar and timezone conventions.

   1. Enumerate every schema property and parameter whose name, description, or example indicates it carries a point in time (createdAt, updatedAt, expiresAt, timestamp, startTime).

   2. Confirm each such field is typed string with format: date-time rather than a bare string, integer epoch, or locale-specific date string.

   3. Inspect every example value. Confirm it is an ISO 8601 datetime ending in a UTC designator (Z or +00:00), not a local-time or offset-bearing value.

   4. Flag any timestamp field that is not ISO 8601, or whose example is expressed in a non-UTC timezone.

2. Lint rule ↗

   The datetime format must be noted in the description so that clients know how the value is encoded.

   components:
     schemas:
       Order:
         type: object
         properties:
           createdAt:
             type: string
             format: date-time
             description: Creation time of the order in ISO 8601 format and UTC.

   Why:

   The description states both the encoding (ISO 8601) and the timezone (UTC), so a consumer reading the documentation knows exactly how to interpret and produce the value.

   components:
     schemas:
       Order:
         type: object
         properties:
           createdAt:
             type: string
             format: date-time
             description: Creation time of the order.

   Why:

   The field is a datetime, but the description says nothing about ISO 8601 or UTC, so a consumer must guess the encoding from an example or trial and error rather than from the documentation.

   Depends on

   IPA 121: Must Use Iso 8601 Utc