Time and Duration (#142)

Timestamps

Timestamp Field Naming

• MUST be in the form <verb-conjugation>_at
• Timestamps that represent a point in time where something has already occurred SHOULD use the past participle conjugation (i.e. created_at)

Timestamp Field Name Examples

Valid

The following are all valid timestamp field names:

• created_at
• updated_at
• deleted_at
• expires_at

Invalid

The following are all invalid timestamp field names:

• created
• create_at
• createdAt
• created-at

Timestamp Values

• MUST be a string in RFC-3339 format
• MUST be in UTC
• MUST denote the UTC timezone using the "Z" suffix
• MUST separate date and time with a "T" character
• MAY include fractional seconds

The following regular expression can be used to validate the format of the timestamp:

\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z

Timestamp Value Examples

Valid

The following are all valid timestamp values:

• "2023-02-27T02:15:00Z"
• "2023-02-27T02:15:00.000Z"
• "2023-02-27T15:00:31"

Invalid

The following are all invalid timestamp values:

• "2023-2-27T02:15:00Z"
• "2023-02-2T02:15:00Z"
• "2023-02-27T15:00:31+00:00"
• "2023-02-27T15:00:31-06:00"
• "2023-02-27 02:15:00Z"
• "2023-02-27T02:15:00"
• 1677527855

Durations

Duration Field Naming

• MUST be in the form <field-name>_<unit-suffix> where unit-suffix denotes the unit of time the value represents.
• The unit suffix MUST be one of:
  • ns
  • ms
  • secs
  • mins
  • hrs
  • days
  • yrs

Duration Field Name Examples

Valid

The following are all valid duration field names:

• ttl_ns
• ttl_ms
• ttl_secs
• flight_duration_mins
• flight_duration_hrs
• lifespan_days
• lifespan_yrs

Invalid

The following are all invalid duration field names:

• ttl
• ttl_seconds
• ttlMS
• lifespan-yrs

Duration Values

Represents a span between two points in time (independent of time zone or calendar). The unit is described by the duration field name.

• MUST be an integer value in the range 0 <= N < 2⁵³

Duration Value Examples

Valid

The following are all valid duration values:

• 5
• 600
• 1000
• 9007199254740991

Invalid

The following are all invalid duration values:

• "60"
• 60.5
• "18ms"
• 9007199254740992