The DateTime interface defines a date and/or time. This interface provides a very broad range of dates, describes more or less precision, and/or conveys an uncertainty. A number of convenience methods for retrieving time elements are available but only those methods covered by the specified granularity are valid.

DateTime is a combination of a date and a time. The behavior of the date portion implies a subtely different behavior than the rest of the interface. What follows is an interpretation based on the Gregorian calendar most of use today.

• Time Values: Elements count up to the next level. There are 1000 milliseconds in a second and 60 minutes in an hour. Each fractional second behaves like it's own clock hand.
• Time Granularity: Elements below (more fine grained) their specified granularity are meaningless. Don't ask for attoseconds at a SECOND granularity.
• Date Granularity: Elements below their specified granularity are meaningless. Don't ask for years at an AEON granularity.
• Date Values: Elements DAY AND MONTH count up to the next level and wraparound like time. There are 12 months in a year.
• Years: Years are proleptic and continue infinitely into the future and back into the past (infinite in this case means the limit of the counter).
• Big Year Values: The largest countable element on a Gregorian Calendar is YEAR. Less granular elements than YEARS (CENTURIES) are calculated from the YEAR. 2026 is CENTURY 21, MILLENNIUM 3, AEON 1.
• Limitations: There is an unspecified practial limitation of 9.22 quintillion years which is plenty of range to put the Big Rip on your calendar. At AEON granularity, that number increases to 9.22 sextiliion. We do expect to see a far future release of the OSIDs to address any limitations describing universe-ending milestones beyond that timeframe.

The counting behavior and the semantic meaning of the elements is determined by the Calendar and Time Systems used although it is expected the fractional second behavior remains constant.

A typical example is describing a day where the time isn't known, and the event did not occur at midnight.

getMillennium() == 2
getCentury() == 18
getYear() == 1776
getMonth() == 7
getDay() == 4
getHour() == 0
getGranularity() == DateTimeResolution.DAY
definesUncertainty() == false
                

Another example showing that the time is probably 1pm but could have been as late as 3pm or early as noon.

getMillennium() == 3
getCentury() == 21
getYear() == 2008
getMonth() == 3
getDay() == 17
getHour() == 13
getMinute() == 0
getGranularity() == TimeResolution.MINUTE
definesUncertainty() == true
getUncertaintyGranularity() == DateTimeResolution.HOUR
getUncertaintyMinus() == 1
getUncertaintyPlus == 2
                

An example marking the birth of the universe. 13.73 billion years +/- 120 million years. The granularity suggests that no more resolution than one million years can be inferred from the "clock", making errors in the exact number of millennia insignificant.

getEpoch() == -13,730
getGranularity() == TimeResolution.EPOCH
definesUncertainty() == true
getUncertaintyGranularity() == DateTimeResolution.EPOCH
getUncertaintyMinus() == 120
getUncertaintyPlus == 120
                

The way to think about granularity versus uncertainty is that granularity is the space between the clock ticks. A clock which displays minutes cannot tell you the second something occurred. Uncertainty is based on the measurement. My digital camera reports times in 100ms increments. That's as granular as it gets. It does not run a NTP client, so it can be a few minutes off. That's its uncertainty.

Finally, uncertainty may be inclusive. Plus or minus 1 year implies the entire two year range of time inclusive of every fractional second in between. A non-inclusive uncertainty implies only three DateTimes -- now, this time 1 year ago, and this time 1 year from now. "This is a photo of the family at Christmas dinner. It could have been 1982 or 1983."