UTC Time as a best practice

As a best practice, we urge everyone publishing to CDS to use either the UTC Time Zone for their RFC timestamps or to have an RFC hour offset based on UTC. You should use this for any given date fields in CDS. Our documentation links back to this tutorial wherever there is a field that expects this best practice.

Why have this?

  • Many of our analytics applications expect to have date fields in UTC time. They use the dates for easy comparison across many different publishers.
  • Likewise APIs such as the Listening Service that read in data from CDS have date logic that assumes UTC.

Using UTC Time as a timezone

Here we’ll use the publishDateTime field from publishable profile as an example of using UTC.

// Wrong method! This is Local Time for Eastern Standard Time (Currently 12:51PM EST)
"publishDateTime": "2024-05-20T12:51:11.135Z"

The above only satisfies the constraint for a RFC3339 format. It is using local time for the user, which can be a problem if any of the use cases listed at the beginning of this document err on the side of UTC. The Z here is indicating Zero hours offset which could be interpreted on a consuming client side as Zero hour offset from UTC and thus be in the past (UTC is +4/5 hours ahead of local time depending on Daylight Savings)

// Corrected using the UTC timezone
"publishDateTime": "2024-05-20T16:51:11.135Z"

Here, the Z is more truthful; we’re stating time in UTC exactly.

Using UTC hourly offset in your timestamp

You can accomplish the same date-time math using an hour offset. See below:

"publishDateTime": "2024-05-20T16:51:11.135-05:00"

© 2024 npr