[ADP-703] Date and Time Field Conventions
Guidelines
- Date and time fields SHOULD have the suffix
At, rather than simply usingtimeortimestamp. - Common terms may be used to represent date or time-related fields, including:
time,date,timestamp,day. - Date and time values MUST be represented using the RFC 3339 format.
Design Considerations
Adding the At suffix clearly indicates that the field is in date-time format, rather than a plain string. While you can refer to documentation for string formats, a good API should be able to semantically describe itself.
If the semantic meaning of the time is unclear, it is acceptable to use common terms like time/timestamp/date/day. For example, in CloudEvents, a time field is defined, but its meaning is not explicitly clear (creation time or current time).
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
Correct Approach:
json
{
"startAt": "2023-10-12T08:00:00Z",
"endAt": "2023-10-12T10:00:00Z"
}DON'T:
json
{
"start": "2023-10-12T08:00:00Z",
"end": "2023-10-12T10:00:00Z",
"occur": "2023-10-12T10:00:00Z"
}