...

So perhaps org.symphonyoss.time.rfc3339 is not an appropriate type for these properties? If so, what type or types should be proposed?

The Argument for org.symphonyoss.time.millis

There are two aspects of the representation of dates and times in formats commonly used by humans:

• Timezones
• Calendar anomalies

Time Zone Issues

With any recorded date/time there may be several actors. Consider the case where the record states that "Alice has been working at Universal Widgets since 9am on June 5th 2017". Let's suppose that Alice is based in London, that the HR department of Universal Widgets (who is the originator of the record) is based in San Francisco, and that Bob, who is receiving a copy of this record is based in New York.

The "start" attribute of this record might be recorded as any of:

• 2017-06-05 09:00 BST (local time as observed by the subject of the record)
• 2017-06-05 08:00 UTC (The standard reference time zone)
• 2017-06-05 01:00 PST (local time as observed by the recorder of the data)
• 1496678400000 (org.symphonyoss.time.millis)

When the date of Alice's employment is displayed to Bob, he may want to see the date in his timezone (none of the values above), or in a standard reference (UTC) or as experienced by Alice (she started work at 9am, not one in the morning or any other time).

If the time is recorded using a standard datum then it can be easily converted to whatever timezone the observer would prefer. If the time could be recorded in any time zone of the originator's choice then consumption of the data is made more complex. When reading a set of records the receiver needs to consider the timezone of each record individually and convert accordingly.

It may be tempting to think that there is some additional information in the timezone, for example, you could reason that "as Alice started work at 9am BST, she must work in London" but this is a complex and indirect way of inferring information which may not have been implied by the originator of the message. If we wanted to specify that the originator is required to record the date in the time zone of the employee then this is quite difficult to explain and is open to misunderstanding. Suppose for some reason Alice was required to be in Berlin for a company meeting on her first day. She did not start work at 9am BST, it could be 9am CEST or 10am BST, if it is recorded as 9am CEST then we might infer that Alice is based in Germany, which she is not. It would be far simpler and more reliable to have a separate "location" attribute and avoid inferences entirely.

Time Zones are something which may be useful when displaying a data record, but different consumers may find different time zones to be more convenient. The time zone at the point when a record is created is irrelevant and recording it is a distraction. All records of time should therefore be made with respect to a standard datum, and UTC is the accepted standard datum for this purpose. An format which represents dates or times in human terms is more complex to process and subject to various failure scenarios. Storage of timestamps as integer values from some epoch has been demonstrated to be more reliable than other methods. Jan 1st 1970 is the Unix epoch, Java has established millisecond values from this epoch as a widely used standard and a 64 bit integer value in this format has the resolution to represent values for dates from before the estimated birth of the universe and well beyond the expected lifespan of the sun. This format (org.symphonyoss.time.millis) is therefore the most appropriate.

Calendar Anomalies

The Gregorian calendar (which is the calendar in use for most "western" cultures today) was introduced on 15th October 1582. Dates before that time were recorded in the Julian calendar, which, among other things, has different rules for when leap years should occur. 

There are also other calendars in current use in certain cultures and timestamps stored in a standard datum format can be converted into dates in the Jewish or Chineese calendars, for example, as needed.

For the purpose of contact entires in a CRM system, events in 1581 may seem unlikely to cause issues, and users who prefer dates reopresented in the Islamic Calendar may not seem like obvious consumers of the data, but as a general rule it would be better to avoid all such issues, which is simply achieved by the use of org.symphonyoss.time.millis.

Resolution Issues

If we want to have attributes representing a date with no timestamp then we could simply define further types which require that valid values must be modulo some constant, for example org.symphonyoss.time.millis.day could require values modulo 86400000.

Roles / Title Standardization / Levels

...