What most serializers do with Date and DateTime values is to use the ISO8601 standard. For example:

# Date format
2011-07-14

# DateTime format
2011-07-14T19:43:37+0100

However, you should be aware that information is lost when you use the Date format. That happens because a Date value might differ between different timezones. Let me give you an example:

• a request was issued at 2011-07-14 T01:00:00Z (UTC) from Brazil (UTC-0300) to a service in UTC
• if the time the request was created is exposed as a Date, it would return the value as 2011-07-14
• but from the client’s perspective in Brazil, the correct date is 2011-07-13, since at the moment of that request was issued, the local time in Brazil was 2011-07-13 T22:00:00-0300

If this information is used only inside your app, within the same timezone, you would have no problems. But, if you need to make this information available through a public API, one of your API’s consumers might recover an incorrect value.

So, from this experience, any date value that will be shared and consumed by different clients should be represented as date time with explicit timezone or using the Unix time format. That way, it is up to the client to treat the data properly.

Here is an example of an API that returns a subscription period in the right way:

{
  period_start_date: 1409175049, # Unix time
  period_end_date: 2014-09-27T18:30:49-0300 # ISO8601
}

# Time.at(1409175049)
# DateTime.parse(“2014-09-27T18:30:49-0300”)

The options above have the advantage that both are unambiguous and sortable. You may choose between one or another based on the fact that the timezone option is easier for human comprehension. But remember that Timezones are a presentation-layer problem, so if you just need to pass data around, Unix time is preferable.

Have you ever had this serialization problem or any other that caused information to be lost? If you have questions or any experience to share, please, leave a comment below.

The post How to serialize Date and DateTime to JSON without losing information first appeared on Plataformatec Blog.