[ADP-703] Date and Time Field Conventions

Guidelines

• Date and time fields SHOULD use a suffix that reflects the data type:
  • At for datetime fields representing a point-in-time instant (e.g., createdAt, expiredAt)
  • Date for date-only fields with no time component (e.g., birthDate, startDate)
  • Time for time-of-day or contextual time fields (e.g., checkoutTime, cutoffTime)
• When both At and Time could apply, prefer At for system-generated point-in-time instants.
• Other common terms (timestamp, day) MAY be used when they fit the domain language naturally.
• Date and time values MUST be represented using the RFC 3339 format.

Design Considerations

Using a type-specific suffix clearly indicates the data format without requiring a documentation lookup. A good API should be able to semantically describe itself.

• Why not bare names? Fields like created, deleted, or start are ambiguous -- they could be booleans, strings, or timestamps. Adding a suffix (createdAt, startDate) eliminates this ambiguity.
• Why distinguish At, Date, and Time? Different suffixes communicate the expected format: At signals a full RFC 3339 datetime with timezone, Date signals a date-only value (YYYY-MM-DD), and Time signals a time-of-day or contextual time concept. Writing birthAt reads unnaturally; birthDate is both clearer and more idiomatic.
• When At and Time overlap: For system-generated lifecycle instants (creation, modification, deletion, expiration), prefer At. Reserve Time for cases where "time" is part of the natural domain language (e.g., checkoutTime, arrivalTime).

For the representation of values, please refer to the requirements for using the RFC 3339 format for date and time.

RFC3339 Format Overview

Refer to the original specification or RFC3339 Overview

Examples

Datetime fields (point-in-time instants) -- use At:

{
  "createdAt": "2023-10-12T08:00:00Z",
  "updatedAt": "2023-10-12T09:30:00Z",
  "expiredAt": "2024-01-01T00:00:00Z"
}

Date-only fields -- use Date:

{
  "birthDate": "1990-05-15",
  "startDate": "2024-01-01",
  "dueDate": "2024-03-31"
}

Contextual time fields -- use Time:

{
  "checkoutTime": "2023-10-12T12:00:00Z",
  "arrivalTime": "2023-10-12T14:30:00Z",
  "cutoffTime": "17:00:00"
}

DON'T -- bare names without suffixes are ambiguous:

{
  "start": "2023-10-12T08:00:00Z",
  "end": "2023-10-12T10:00:00Z",
  "created": "2023-10-12T10:00:00Z"
}

Reference

Specifications

• RFC 3339

Design References

• https://opensource.zalando.com/restful-api-guidelines/#235
• https://google.aip.dev/142
• https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md
• https://criteria.sh/blog/rest-api-date-format-best-practices