Skip to content

Commit

Permalink
fix: Date Time ISO 8601 Enhanced Examples (#58)
Browse files Browse the repository at this point in the history
* Enhanced examples on Date Time Formatting

* Move the timezone specific example to incorrect
  • Loading branch information
travisgosselin authored Jul 13, 2023
1 parent 4eddeed commit c190e92
Showing 1 changed file with 8 additions and 5 deletions.
13 changes: 8 additions & 5 deletions standards/serialization.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,22 +236,25 @@ If there is an industry standard that requires us to do otherwise, enums **MAY**
[JSON](https://json.org) itself **does not** specify how dates should be represented, but most organizations use the date specification described in JavaScript.

- All dates posted in requests and returned in response **MUST** conform to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard (format `YYYY-MM-DDTHH:mm:ss.sssZ`).
- All dates **MUST** include the correct time zone.
- All dates **MUST** include the time zone, and **SHOULD** be represented in UTC time zone.
- All date fields **SHOULD** have the level of specificity and accuracy in their name:
- `xxxDateTime` for fields with accuracy to time level
- `xxxDate` for fields with accuracy to date level

```
// INCORRECT
{
createdDate: "May 16 2021 14:12:07", // date format incorrect, name of the field indicates Date but value has DateTime
createdDateTime: "May 16 2021", // specified value does not contain time portion
created: "2021-05-16T14:12:07" // name of the field does not indicate that it is DateTime field
createdDate: "May 16 2021 14:12:07", // date format incorrect, name of the field indicates Date but value has DateTime
createdDateTime: "May 16 2021", // specified value does not contain time portion
created: "2021-05-16T14:12:07" // name of the field does not indicate that it is DateTime field
localDateTime: "2021-05-16T14:12:07", // while valid ISO 8601 format for local time zone, it is not appropriate for these API standards.
zoneDateTime: "2021-05-16T14:12:07−05:00", // should use UTC time zone specified by Z at the end of the string
}
// CORRECT
{
createdDateTime: "2021-05-16T14:12:07−05:00"
preciseDateTime: "2021-05-16T14:12:07.123Z", // standard date time with sub-second precision
createdDateTime: "2021-05-16T14:12:07Z", // standard date time with second precision
}
```

Expand Down

0 comments on commit c190e92

Please sign in to comment.