Date Time Data Types
Recommendation, 2007 April 15
Editor:
Don Simonson, Robert Haft International
Eric Johns, ESOXML
Karl Brophey, EbenX
Kim Bartkus, HR-XML
Scott Miller, IBM
Paul Kiel, HR-XML
Tim Farlow, Authoria
Authors:
Mark Marsden, Ultimate Software
Contributors:
Members of Cross Process Objects workgroup
Copyright © 2007 HR-XML Consortium, Inc.
Abstract
The date, time and dateTime data types provided in the Schema Recommendation allows for an optional time zone designation. In Consortium work, there will be times when the precise date, time or dateTime value must be known. The objective of this document is to provide HR-XML Schema designers the ability to require or prohibit the Time Zone designation for date, time and dateTime values in a consistent manner.
Status of this Document
2006-02-28: “xsd:union” is one of the least supported features of XML Schema in developer tools. DateTimeDataTypes uses xsd:union as a way to enable “notApplicable” or “notKnown” to be specified within a date field. HR-XML’s Technical Steering Committee has recommended the removal of all unions in future releases. Certain types defined within this specification will be affected by this recommendation in a later release.
Table of Contents
1.3.2 Items Within the Design Scope
1.3.3 Items Outside of Design Scope
2 Supported Business Processes
2.2 Business Process Decision Drivers
3.1.2 Schema Elements Explained
4 Implementation Considerations
6 Appendix B – Character Representations and Designators
7 Appendix C - Document Version History
8 Appendix D - Related Documents
9 Appendix E – Reference Examples
1 Overview
1.1 Objective
The objective of this document is to provide HR-XML Schema designers the tools to incorporate date, time and dateTime values into their work processes in a consistent manner. This is achieved through the use of standard data types, which permit an XML parser to ensure the validity of a desired style of data. Each work group can define its own business process needs and apply any of the applicable "dateTime" data types defined herein which match that need.
1.1.1 Domain Issues
In the HR space, there are many instances where a point in time needs to be captured. The preciseness of the date/time value is often dependent on the business context. A hire date can often be captured as date value, the exact time a person is hired is not important in many transactions. An incident date requires more precision. Many transactions require the date and time an incident took place. Also, in the case of an incident, the time zone may be required. Eleven o’clock in the evening on July 31 in Washington DC, is four o’clock in the morning on August 1 in London. This could mean a difference in coverage for the employee.
Another issue with the current Schema Recommendation is the fact that the time zone designation is optional. A business partner can receive multiple instance documents based on the same schema design. Some documents can contain a dateTime data element that has the time zone, and some of the documents can contain the same dateTime data element that does not contain the time zone. The business partner has no way of ordering the documents based on this dateTime date element.
1.1.2 Business Reasons
Almost all HR and Payroll business processes revolve around some event or string of events in time. All these events have in common a start point, an end point, a duration, or some combination of these, that must be represented in a format that can be efficiently stored, conveyed and processed by HRIS systems. By developing a standard approach to providing date information we will prevent the necessity of other HR-XML Consortium work groups from devoting time and effort to addressing this on a case-by-case basis.
1.2 Design Requirements
The date, time and dateTime data types provided in the Schema Recommendation of May 2, 2001 allows for an optional time zone designation. In Consortium work, there will be times when the precise date, time or dateTime value must be known. The objective of this document is to provide HR-XML Schema designers the ability to require or prohibit the TimeZone designation for date, time and dateTime values in a consistent manner.
The Design requirements must take into account the following:
1. A global concept of time
2. Representing Date and Time values in Schema
3. Allow a Date and/or Time value to be stored as a data element or as a data attribute
1.3 Scope
1.3.1 Major Components
Deliver standard Date, Time and DateTime data types that will be used by all of the work groups within the consortium. The goal is consistency.
Provide a yardstick that the CPO can use as a basis for reviewing other workgroup’s schema designs.
1.3.2 Items Within the Design Scope
Representing a point in time
Representing a time period (An interval of time with a start and an end)
Representing an unknown date, time or date/time value
Representing an open ended date/time value
Provide standard data types for:
1. Local Date, Local Time, Local DateTime
2. Global Date, Global Time, Global DateTime
1.3.3 Items Outside of Design Scope
Time scheduling rules, such as ‘7 days before Christmas’ are not addressed in this document. Likewise scheduling items of the form ‘Every Tuesday at 10:00AM’ or ‘Every Monday through Friday from 3:30PM to 4:00PM’ is not addressed in this document. It is encouraged that for these needs the relevant schema data types be used when possible.
Representing a “duration of time” (2 days, 4 hours, 13 minutes) will not be addressed in this version of the document.
Representing a partial date, such as 2001-06 or a partial time, such as 12:00.
2 Supported Business Processes
2.1 Trading Partner Roles
The purpose of this recommendation is to provide a standard representation for date and time values to schema designers within the consortium, trading partner roles do not apply to this document.
2.2 Business Process Decision Drivers
Before reading this section, you should have a good understanding of the vocabulary defined in Appendix A.
Once it has been determined that a time value needs to be captured, the schema designer should consider how the following issues affect the time value being captured:
Local Time vs. Global Time – If the time value being communicated is representative of a specific point in time in a specific location, then a global time value should be captured. If the time being communicated is representative of a relative point in time, independent of time zone, then a local time value should be used. When in doubt, use a global time value.
Consider the following examples:
Global Time Value:
Business A is located in Washington DC (5 hours behind UTC).
Business B is located in London (0 hours behind UTC).
Business A sends a time value of 2001-04-01T09:30:00 for an employee living in California (8 hours behind UTC).
Problem: How can business B determine the correct time the event really happened? Is it 9:30 Washington time, 9:30 California time or 9:30 London time?
Solution: Business A sends a time value of 2001-04-01T09:30:00-05:00. Now its clear that the time the event occurred was 9:30 Washington time. Business B can use this information to calculate the time the event occurred in California time or London time as well.
Local Time Value:
An employee lives and works in California (8 hours behind UTC).
The employee's benefit plan, including medical coverage, becomes effective at
midnight 2000-08-01 local time. This applies to claims incurred on or after
that point in time, where they seek care.
Problem: The employee has an accident requiring medical attention at 2000-08-01T02:00:00 London Time. (2000-07-31T17:00:00 California Time). Is the medical coverage in effect?
Solution: The coverage is in effect on 2000-08-01. The accident occurred at 2000-08-01T02:00:00+00:00. Since one date has a time zone and the other does not, the system should consider the coverage in effect (Year, Month and Day are equal). By explicitly not sending the time zone, it is being communicated that the start of coverage is 2000-08-01. Had the accident occurred at the same point in time, but in California instead of London, the coverage would not be in effect.
Precision – Is the date precise enough, or is a
specific point in time (date & time) required?
A hire date is an example where the date value is usually precise enough.
Most employers are not concerned with the exact second an employee was
hired. An incident date, on the other hand may require a precise date and
time value. The time of day may be all that’s required for a child data
element when the parent data element contains the date.
Unbounded / Not Applicable Date Values – Is it acceptable to have a date value that conveys a ‘maximum date’ value, a ‘minimum date’ value or ‘date value does not apply’? This is common in date ranges. An employee’s start date is 2001-04-01. The currently employed employee’s termination date has yet to be determined. For processing purposes we want to convey the termination date is notApplicable.
Unknown Date Values – Is it possible for the sending system to not know the date value being captured? Is this acceptable? If so, we want to be able to communicate this state to the receiving system. This is done using the notKnown value. An employee’s start date is 2001-04-01. The sending system does not know the current status of the employee. It would send the notKnown value in the employee’s termination date.
3 Schema Design
The best way to explain the CPO Date Data types is to describe how a designer might want their data element/attribute to behave. The issue with the Schema Date, Time and DateTime data types is that they are a little too lenient when it comes to the time zone designator. Most likely, the schema designer will want to enforce or prohibit the time zone designator of the date/time value. This would provide a consistent format for date/time values received in any given element/attribute. The date/time data type names can be broken down as follows:
short description - The value the element/attribute represents (i.e. Date, Time, DateTime) Any description with the word ‘Local’ before the short description, defines a value that does not contain a time zone designator. Descriptions without the word ‘Local’ define a value that must contain a time zone designator, and will contain a global time value or a value that can be easily converted to a global time value.
Nk – The data element/attribute can contain a valid date/time value or the word notKnown
Na – The data element/attribute can contain a valid date/time value or the word notApplicable
Type – Indicates that this name is not meant to be a data element/attribute name, but is meant to be the foundation for the data elements and attributes.
For example an element/attribute of type LocalDateNkNaType will contain a valid date value in the format of YYYY-MM-DD, or the value notKnown, or the value notApplicable. The element/attribute cannot contain any other value. (If it does, the full document will be considered not valid.)
|
Data Type |
Basic Format |
Time |
not
Known |
not |
|
DateType |
YYYY-MM-DD(Z | ±hh:mm) |
Yes |
|
|
|
DateNkType |
YYYY-MM-DD(Z | ±hh:mm) |
Yes |
Yes |
|
|
DateNaType |
YYYY-MM-DD(Z | ±hh:mm) |
Yes |
|
Yes |
|
DateNkNaType |
YYYY-MM-DD(Z | ±hh:mm) |
Yes |
Yes |
Yes |
|
LocalDateType |
YYYY-MM-DD |
|
|
|
|
LocalDateNkType |
YYYY-MM-DD |
|
Yes |
|
|
LocalDateNaType |
YYYY-MM-DD |
|
|
Yes |
|
LocalDateNkNaType |
YYYY-MM-DD |
|
Yes |
Yes |
|
TimeType |
hh:mm:ss(Z | ±hh:mm) |
Yes |
|
|
|
TimeNkType |
hh:mm:ss(Z | ±hh:mm) |
Yes |
Yes |
|
|
TimeNaType |
hh:mm:ss(Z | ±hh:mm) |
Yes |
|
Yes |
|
TimeNkNaType |
hh:mm:ss(Z | ±hh:mm) |
Yes |
Yes |
Yes |
|
LocalTimeType |
hh:mm:ss |
|
|
|
|
LocalTimeNkType |
hh:mm:ss |
|
Yes |
|
|
LocalTimeNaType |
hh:mm:ss |
|
|
Yes |
|
LocalTimeNkNaType |
hh:mm:ss |
|
Yes |
Yes |
|
DateTimeType |
YYYY-MM-DDThh:mm:ss(Z | ±hh:mm) |
Yes |
|
|
|
DateTimeNkType |
YYYY-MM-DDThh:mm:ss(Z | ±hh:mm) |
Yes |
Yes |
|
|
DateTimeNaType |
YYYY-MM-DDThh:mm:ss(Z | ±hh:mm) |
Yes |
|
Yes |
|
DateTimeNkNaType |
YYYY-MM-DDThh:mm:ss(Z | ±hh:mm) |
Yes |
Yes |
Yes |
|
LocalDateTimeType |
YYYY-MM-DDThh:mm:ss |
|
|
|
|
LocalDateTimeNkType |
YYYY-MM-DDThh:mm:ss |
|
Yes |
|
|
LocalDateTimeNaType |
YYYY-MM-DDThh:mm:ss |
|
|
Yes |
|
LocalDateTimeNkNaType |
YYYY-MM-DDThh:mm:ss |
|
Yes |
Yes |
|
AnyDateTimeType |
YYYY-MM-DD |
Optional |
|
|
|
AnyDateTimeNkType |
YYYY-MM-DD |
Optional |
Yes |
|
|
AnyDateTimeNaType |
YYYY-MM-DD |
Optional |
|
Yes |
|
AnyDateTimeNkNaType |
YYYY-MM-DD |
Optional |
Yes |
Yes |
|
· (Z | ±hh:mm) means that either the letter Z or a time zone designator in the form of +hh:mm or -hh:mm is allowed. ·
In all of the Basic Formats with a time
zone designator (±hh:mm), · When the letter Z is used in a DateTime expression the value is said to be a Coordinated Universal Time value. ·
When the time zone designator (±hh:mm) is used in a DateTime
expression, the value is a local time value. · All of the following are true: · 2001-04-01T06:00:00-05:00 = 2001-04-01T11:00:00Z · 2001-04-01T06:00:00+07:00 = 2001-03-31T23:00:00Z · 2001-04-01T06:00:00+00:00 = 2001-04-01T06:00:00Z ·
The only valid formats for Coordinated
Universal Time are the following: |
||||
3.1 Schema Details
3.1.1 Schema Diagrams
The purpose of this document is to define data types for use with data elements/attributes that contain a date or a date/time value. A Schema diagram does not apply for this document. Please review the Reference Examples in appendix B for sample diagrams/schemas using the data types defined in this document. Appendix C contains the Schema source for these data types.
3.1.2 Schema Elements Explained
|
Component Name
|
ContentModel |
Definition |
|
Global simpleTypes: |
|
|
|
/ |
xsd:restriction base: xsd:string [Enumerations]: notKnown |
Allows only the value ‘notKnown’ to be a valid value for elements/attributes of this type |
|
/ |
xsd:restriction base: xsd:string [Enumerations]: notApplicable |
Allows only the value notApplicable to be a valid value for elements/attributes of this type |
|
/ |
xsd:restriction base: xsd:date |
Allows
only a valid date value to be entered in the format
The parser will verify that the value is a valid date. |
|
/ |
- [Union]: LocalDateType, NotKnownLiteral |
Allows
the value ‘notKnown’ or a valid date value in the format:
The parser will verify that the value is a valid date. |
|
/ |
- [Union]: LocalDateType, NotApplicableLiteral |
Allows the value ‘notApplicable’ or a valid date value in the format: LocalDateType
The parser will verify that the value is a valid date. |
|
/ |
- [Union]: LocalDateType, NotKnownLiteral, NotApplicableLiteral |
Allows
the value ‘notKnown’, ‘notApplicable’, or a
valid date value in the format:
The parser will verify that the value is a valid date. |
|
/ |
xsd:restriction base: xsd:date |
Allows
only a valid date value to be entered in the formats:
The parser will verify that it is a valid date and time zone. |
|
/ |
- [Union]: DateType, NotKnownLiteral |
Allows
the value ‘notKnown’ or a valid date value in the format:
The parser will verify that it is a valid date and time zone. |
|
/ |
- [Union]: DateType, NotApplicableLiteral |
Allows
the value ‘notApplicable’ or a valid date value in the
format:
The parser will verify that it is a valid date and time zone. |
|
/ |
- [Union]: DateType, NotKnownLiteral, NotApplicableLiteral |
Allows
the value ‘notKnown’, ‘notApplicable’, or a
valid date value in the format:
The parser will verify that it is a valid date and time zone. |
|
/ |
xsd:restriction base: xsd:time |
Allows only
a valid time value to be entered in the following format: |
|
/ |
- [Union]: LocalTimeType, NotKnownLiteral |
Allows
the value ‘notKnown’ or a valid time value in the format:
The parser will verify that the value is a valid time. |
|
/ |
- [Union]: LocalTimeType, NotApplicableLiteral |
Allows the value ‘notApplicable’ or a valid time value |