Network Working Group C. Daboo
Internet-Draft Apple Inc.
Updates: 5545, 4791 (if approved) G. Yakushev
Intended status: Standards Track Google Inc.
Expires: September 16, 2014 March 15, 2014
Non-Gregorian Recurrence Rules in iCalendar
draft-daboo-icalendar-rscale-03
Abstract
This document defines how non-Gregorian recurrence rules can be
specified in iCalendar data.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 16, 2014.
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Daboo & Yakushev Expires September 16, 2014 [Page 1]
Internet-Draft iCalendar Property Extensions March 2014
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 4
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Extended RRULE Property . . . . . . . . . . . . . . . . . . . 6
4.1. Handling Leap Months . . . . . . . . . . . . . . . . . . . 7
4.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7
5. Registering Calendar Systems . . . . . . . . . . . . . . . . . 9
6. Use with iTIP . . . . . . . . . . . . . . . . . . . . . . . . 9
7. Use with CalDAV . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. CALDAV:supported-rscale-set Property . . . . . . . . . . . 11
8. Security Considerations . . . . . . . . . . . . . . . . . . . 12
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12
11. Normative References . . . . . . . . . . . . . . . . . . . . . 12
Appendix A. Change History (To be removed by RFC Editor
before publication) . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
Daboo & Yakushev Expires September 16, 2014 [Page 2]
Internet-Draft iCalendar Property Extensions March 2014
1. Introduction
The iCalendar [RFC5545] data format is in widespread use to represent
calendar data. iCalendar represents dates and times using the
Gregorian calendar system only. It does provide a way to use non-
Gregorian calendar systems via a "CALSCALE" property, however this
has never been formally used. However, there is a need to support at
least non-Gregorian recurrence patterns to cover anniversaries, and
many local, religious, or civil holidays based on non-Gregorian
dates.
There are several disadvantages to using the existing "CALSCALE"
property in iCalendar for implementing non-Gregorian calendars:
1. The "CALSCALE" property exists in the top-level "VCALENDAR"
objects and thus applies to all components within that object.
In today's multi-cultural society, that restricts the ability to
mix events from different calendar systems within the same
iCalendar object. e.g., it would prevent having both the
Gregorian New Year and Chinese New Year in the same iCalendar
object.
2. Many countries observe daylight savings time, encoded in
iCalendar using the "VTIMEZONE" component. Timezone and daylight
saving time rules are always specified via Gregorian calendar
based recurrence rules (e.g., "the 3rd Sunday in March"). This
is problematic for non-Gregorian uses of "CALSCALE" which would
by default also apply to the dates and rules used in the
"VTIMEZONE" components in the corresponding iCalendar object.
This specification solves these issues by allowing the "CALSCALE" to
remain set to Gregorian, but re-defining the recurrence rule property
"RRULE" to accept new items including one that allows non-Gregorian
calendar systems to be used. With this, all the date, time and
period values in the iCalendar object would remain specified using
the Gregorian calendar system, but repeating patterns in other
calendar systems could be defined. It is then up to calendar user
agents and servers to map between Gregorian and non-Gregorian
calendar systems in order to expand out recurrence instances.
This specification does not itself define calendar systems, rather it
utilizes the registry defined by the Unicode Consortium
(http://unicode.org) in their CLDR (Common Locale Data Repository)
project.
Daboo & Yakushev Expires September 16, 2014 [Page 3]
Internet-Draft iCalendar Property Extensions March 2014
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
The notation used in this memo is the ABNF notation of [RFC5234] as
used by iCalendar [RFC5545]. Any syntax elements shown below that
are not explicitly defined in this specification come from iCalendar
[RFC5545], iTIP [RFC5546], and CalDAV [RFC4791].
When XML element types in the namespaces "DAV:" and
"urn:ietf:params:xml:ns:caldav" are referenced in this document
outside of the context of an XML fragment, the string "DAV:" and
"CALDAV:" will be prefixed to the element type names respectively.
When a Gregorian calendar date value is shown in text, it will use
the format "YYYYMMHH", where "YYYY" is the 4-digit year, "MM" the
2-digit month, and "DD" the 2-digit day (this is the same format used
in iCalendar [RFC5545]). The Chinese calendar will be used as an
example of a non-Gregorian calendar for illustrative purposes. When
a Chinese calendar date value is shown in text, it will use the
format "{C}YYYYMM[L]DD" - i.e., the same format as Gregorian but with
a "{C}" prefix, and an optional "L" character after the month element
to indicate a leap month. Similarly, {I} and {H} are used in other
examples as prefixes for Islamic (Civil) and Hebrew dates,
respectively. Note that the Chinese calendar years shown in the
examples are based on the Unicode (ICU) library's Chinese calendar
epoch. Whilst there are several different Chinese calendar epochs in
common use, the choice of one over another does not impact the actual
calculation of the Gregorian equivalent dates, provided conversion is
always done using the same epoch.
3. Overview
In the Gregorian calendar system, each year is composed of a fixed
number of months (12), with each month having a fixed number of days
(between 30 and 31), except for the second month (February) which
contains either 28 days, or 29 days (in a leap year). Weeks are
composed of 7 days, with day names Monday, Tuesday, Wednesday,
Thursday, Friday, Saturday and Sunday. Years can have either 365 or
366 days (the later in a leap year). The number of whole weeks in a
year is 52.
In iCalendar, the "RECUR" value type defines various fields used to
express a recurrence pattern, and those fields are given limits based
Daboo & Yakushev Expires September 16, 2014 [Page 4]
Internet-Draft iCalendar Property Extensions March 2014
on those of the Gregorian calendar system. Since other calendar
systems can have different limits and other behaviors that need to be
accounted for, the maximum values for the elements in the "RECUR"
value are not covered by this specification.
To generate a set of recurring instances in a non-Gregorian calendar
system, the following procedure is used:
1. iCalendar data continues to use the "GREGORIAN" calendar system,
so all "DATE", "DATE-TIME" and "PERIOD" values continue to use
the Gregorian format and limits.
2. The "RRULE" property is extended to include an "RSCALE" element
in its value that specifies the calendar system to use for the
recurrence pattern. The existing elements of the "RRULE" value
type are used, but modified to support different upper limits,
based on the "RSCALE" value, as well as a modification to month
numbers to allow a leap month to be specified. Existing
requirements for the use of "RRULE" all still apply (e.g., the
"RRULE" has to match the "DTSTART" value of the master instance).
Other recurrence properties such as "RECURRENCE-ID", "RDATE" and
"EXDATE" continue to use the Gregorian date format as "CALSCALE"
is unchanged.
When generating instances, the following procedure might be used:
1. Convert the "DTSTART" property value of the master recurring
component into the date and time components for the calendar
system specified by the "RSCALE" element in the "RRULE" value.
This provides the "seed" value for generating subsequent
recurrence instances.
2. Iteratively generate instances using the "RRULE" value applied to
the year, month, and day components of the date in the new
calendar system.
3. For each generated instance, convert the date values back from
the non-Gregorian form into Gregorian and use those values for
other properties such as "RECURRENCE-ID".
Consider the following example for an event representing the Chinese
New Year:
DTSTART;VALUE=DATE:20130210
RRULE:RSCALE=CHINESE;FREQ=YEARLY
SUMMARY:Chinese New Year
To generate instances, first the "DTSTART" value "20130210" is
Daboo & Yakushev Expires September 16, 2014 [Page 5]
Internet-Draft iCalendar Property Extensions March 2014
converted into the Chinese calendar system giving "{C}46500101".
Next, the year component is incremented by one to give "{C}46510101",
and that is then converted back into Gregorian as "20140131".
Additional instances are generated by iteratively increasing the year
component in the Chinese date value and converting back to Gregorian.
This specification makes use of calendar algorithms defined by the
Unicode Consortium [TBD - reference]. The definition of different
calendar scales is defined by Unicode, as per Section 5.
4. Extended RRULE Property
This specification extends the existing "RRULE" iCalendar property
value to include a new "RSCALE" element that can be used to indicate
the calendar system used for generating the recurrence pattern.
When "RSCALE" is present, the other changes to "RRULE" are:
1. Elements that include numeric values (e.g., "BYYEARDAY") have
numeric ranges defined by the "RSCALE" value (i.e., in some
calendar systems there might be more than 366 days in a year).
2. Month numbers can include an "L" suffix to indicate that the
specified month is a leap month in the corresponding calendar
system.
3. Month numbers can be specified using a negative offset (i.e.,
"-1" represents the last month of the year).
4. A "SKIP" element is added to define how "missing" instances are
handled. e.g., if a yearly recurring event starts in a leap
month, the "SKIP" element determines whether instances in non-
leap years are ignored ("SKIP" set to "YES"), appear in the
preceding regular month ("SKIP" set to "BACKWARD" - the default
when "RSCALE" is present), or appear in the following regular
month ("SKIP" set to "FORWARD"). The "SKIP" processing is done
after all other rule elements except for "COUNT" and "UNTIL" have
been processed.
The syntax for the "RECUR" value is modified in the following
fashion:
Daboo & Yakushev Expires September 16, 2014 [Page 6]
Internet-Draft iCalendar Property Extensions March 2014
recur-rule-part /= ("RSCALE" "=" rscale)
/ ("SKIP" "=" skip)
rscale = (iana-token ; A CLDR-registered calendar system
; name.
/ x-name) ; A non-standard, experimental
; calendar system name.
skip = ("YES" / "BACKWARD" / "FORWARD")
; When "RSCALE" is not present the default
; is "YES". When "RSCALE" is present the default
; is "BACKWARD".
monthnum = [plus / minus] 1*2DIGIT ["L"]
; Existing element modified to include a positive
; or negative offset capability, as well as a leap
; month indicator suffix.
4.1. Handling Leap Months
Leap months can occur in different calendar systems. For most of
those, the suffix "L" is added to the "RRULE" month number component
to indicate a leap month. In some cases the month precedes the
regular month with the same number, in other cases it follows. The
one exception to this rule is the Hebrew calendar, where we follow
the definition from Unicode [TBD - REF]. In that case months are
number 1 through 13, with month 6 being the leap month. Thus in non-
leap years, month 6 is skipped.
4.2. Examples
4.2.1. Chinese New Year
Consider the following set of iCalendar properties:
DTSTART;VALUE=DATE:20130210
RRULE:RSCALE=CHINESE;FREQ=YEARLY
SUMMARY:Chinese New Year
These define a recurring event for the Chinese New Year, with the
first instance the one in Gregorian year 2013.
The Chinese date corresponding to the first instance is {C}46500101.
The table below shows the initial instance, and the next four, each
of which is determined by adding the appropriate amount to the year
component of the Chinese date. Also shown is the conversion back to
the Gregorian date:
Daboo & Yakushev Expires September 16, 2014 [Page 7]
Internet-Draft iCalendar Property Extensions March 2014
+--------------+------------------------------------------------+
| Chinese Date | Gregorian Date |
+--------------+------------------------------------------------+
| {C}46500101 | 20130210 - DTSTART specified in iCalendar data |
| {C}46510101 | 20140131 |
| {C}46520101 | 20150219 |
| {C}46530101 | 20160208 |
| {C}46540101 | 20170128 |
+--------------+------------------------------------------------+
4.2.2. Islamic Civil Start of Ramadan
Consider the following set of iCalendar properties:
DTSTART;VALUE=DATE:20130709
RRULE:RSCALE=ISLAMIC-CIVIL;FREQ=YEARLY;BYMONTH=9
SUMMARY:Start of Ramadan
These define a recurring event for the start of the Islamic month of
Ramadan, with the first instance the one in Gregorian year 2013.
The Islamic date corresponding to the first instance is {I}14340901.
The table below shows the initial instance, and the next four, each
of which is determined by adding the appropriate amount to the year
component of the Islamic date. Also shown is the conversion back to
the Gregorian date:
+--------------+------------------------------------------------+
| Islamic Date | Gregorian Date |
+--------------+------------------------------------------------+
| {I}14340901 | 20130709 - DTSTART specified in iCalendar data |
| {I}14350901 | 20140629 |
| {I}14360901 | 20150618 |
| {I}14370901 | 20160607 |
| {I}14380901 | 20170527 |
+--------------+------------------------------------------------+
Note that in this example, the value of the "BYMONTH" component in
the "RRULE" matches the Islamic month value and not the Gregorian
month.
4.2.3. Hebrew anniversary starting in a leap month
Consider the following set of iCalendar properties:
DTSTART;VALUE=DATE:20140208
RRULE:RSCALE=HEBREW;FREQ=YEARLY;BYMONTH=6;BYMONTHDAY=8;SKIP=FORWARD
SUMMARY:Anniversary
Daboo & Yakushev Expires September 16, 2014 [Page 8]
Internet-Draft iCalendar Property Extensions March 2014
These define a recurring event for the 8th day of the Hebrew month of
Adar I, with the first instance the one in Gregorian year 2014.
The Hebrew date corresponding to the first instance is {H}57740608,
note that month 6 is a leap month in year 5774. The table below
shows the initial instance, and the next four, each of which is
determined by adding the appropriate amount to the year component of
the Hebrew date, taking into account that only year 5776 is a leap
year. Thus in other years the Hebrew month component is adjusted
forward to month 7. Also shown is the conversion back to the
Gregorian date:
+-------------+------------------------------------------------+
| Hebrew Date | Gregorian Date |
+-------------+------------------------------------------------+
| {H}57740608 | 20140208 - DTSTART specified in iCalendar data |
| {H}57750708 | 20150227 |
| {H}57760608 | 20160217 |
| {H}57770708 | 20170306 |
| {H}57780708 | 20180223 |
+-------------+------------------------------------------------+
5. Registering Calendar Systems
This specification uses the Unicode Consortium's registry of calendar
systems [UNICODE.CLDR] to define valid values for the "RSCALE"
element of an "RRULE". Note that the underscore character "_" is
never used in CLDR-based calendar system names. New values can be
added to this registry following Unicode Consortium rules. It is
expected that many implementations of non-Gregorian calendars will
use software libraries provided by Unicode (ICU), and hence it makes
sense to re-use their registry rather than creating a new one. For
consistency, when used, the "RSCALE" values SHOULD be uppercased.
CLDR supports the use of "alias" values as alternative names for
specific calendar systems. These alias values MUST be treated as
valid "RSCALE" element values.
When using the CLDR data, calendar agents SHOULD take into account
the "deprecated" value and use the alternative "preferred" calendar
system. In particular, the "islamicc" calendar system is considered
deprecated in favor of the "islamic-civil" calendar system.
6. Use with iTIP
iTIP [RFC5546] defines how iCalendar data can be sent between
Daboo & Yakushev Expires September 16, 2014 [Page 9]
Internet-Draft iCalendar Property Extensions March 2014
calendar user agents to schedule calendar components between calendar
users. It is often not possible to know the capabilities of a
calendar user agent to which an iTIP message is being sent, but iTIP
defines fallback behavior in such cases.
For calendar user agents that do not support the "RSCALE" element,
the following can occur when iTIP messages containing an "RSCALE"
element are received:
The receiving calendar user agent can reject the entire iTIP
message and return an iTIP reply with a "REQUEST-STATUS" property
set to the "3.1" status code (as per Section 3.6.14 of [RFC5546]).
The receiving calendar user agent can fallback to a non-recurring
behavior for the calendar component (effectively ignoring the
"RRULE" property) and return an iTIP reply with a "REQUEST-STATUS"
property set to the "2.3", "2.5", "2.8", or "2.10" status codes
(as per Sections 3.6.3, 3.6.6, 3.6.9, or 3.6.11, respectively, of
[RFC5546]).
For calendar user agents that support the "RSCALE" element but do not
support the calendar system specified by the "RSCALE" element value,
the following can occur:
the iTIP message SHOULD be rejected, returning a "REQUEST-STATUS"
property set to the "3.1" status code (as per Section 3.6.14 of
[RFC5546]).
if the iTIP message is accepted and the calendar component treated
as non-recurring, an iTIP reply with a "REQUEST-STATUS" property
set to the "2.8" or "2.10" status codes (as per Sections 3.6.9 or
3.6.11, respectively, of [RFC5546]) SHOULD be returned.
7. Use with CalDAV
The CalDAV [RFC4791] calendar access protocol allows clients and
server to exchange iCalendar data. In addition, CalDAV clients are
able to query calendar data stored on the server, including time-
based queries. Since an "RSCALE" element value determines the time
ranges for recurring instances in a calendar component, CalDAV
servers need to support it to interoperate with clients also using
the "RSCALE" element.
A CalDAV server advertises a CALDAV:supported-rscale-set WebDAV
property on calendar home or calendar collections if it supports use
of "RSCALE" element as described in this specification. The server
can advertise a specific set of supported calendar systems by
Daboo & Yakushev Expires September 16, 2014 [Page 10]
Internet-Draft iCalendar Property Extensions March 2014
including one or more CALDAV:supported-rscale XML elements within the
CALDAV:supported-rscale-set XML element. If no CALDAV:supported-
rscale XML elements are included in the WebDAV property, then clients
can try any calendar system value, but need to be prepared for a
failure when attempting to store the calendar data.
Clients MUST NOT attempt to store iCalendar data containing "RSCALE"
elements if the CALDAV:supported-rscale-set WebDAV property is not
advertised by the server.
The server SHOULD return an HTTP 403 response with a DAV:error
element containing a CALDAV:supported-rscale XML element, if a client
attempts to store iCalendar data with an "RSCALE" element value not
supported by the server.
It is possible for a "RSCALE" value to be present in calendar data on
the server being accessed by a client that does not support an
"RSCALE" element or its specified value. It is expected that
existing clients, unaware of "RSCALE", will fail gracefully by
ignoring the calendar component, whilst still processing other
calendar data on the server.
7.1. CALDAV:supported-rscale-set Property
Name: supported-rscale-set
Namespace: urn:ietf:params:xml:ns:caldav
Purpose: Enumerates the set of supported iCalendar "RSCALE" element
values supported by the server.
Protected: This property MUST be protected and SHOULD NOT be
returned by a PROPFIND allprop request (as defined in Section 14.2
of [RFC4918]).
Description: See above.
Definition:
Example:
Daboo & Yakushev Expires September 16, 2014 [Page 11]
Internet-Draft iCalendar Property Extensions March 2014
gregorian
chinese
islamic-civil
hebrew
8. Security Considerations
This specification does not introduce any addition security concerns
beyond those described in [RFC5545], [RFC5546], and [RFC4791].
9. IANA Considerations
This specification does not define any new IANA registries or values.
10. Acknowledgments
Thanks to the following for feedback: Mark Davis, Mike Douglass,
Peter Edberg, Arnaud Quillaud, and Dave Thewlis. This specification
came about via discussions at the Calendaring and Scheduling
Consortium.
11. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
March 2007.
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
Core Object Specification (iCalendar)", RFC 5545,
September 2009.
[RFC5546] Daboo, C., "iCalendar Transport-Independent
Daboo & Yakushev Expires September 16, 2014 [Page 12]
Internet-Draft iCalendar Property Extensions March 2014
Interoperability Protocol (iTIP)", RFC 5546,
December 2009.
[UNICODE.CLDR]
"CLDR calendar.xml Data", Unicode Consortium CLDR,
August 2013, .
Appendix A. Change History (To be removed by RFC Editor before
publication)
Changes in -03:
1. Added details about handling RSCALE in iTIP.
2. Added details about handling RSCALE in CalDAV.
3. Fixed examples to use ICU Chinese epoch and added text describing
why that is not an issue for actual recurrence calculations.
Changes in -02:
1. Fixed some incorrect dates in examples.
2. Clarified use of CLDR and alias, deprecated, preferred
attributes.
3. Clarified when SKIP processing occurs.
Changes in -01:
1. Removed requirement that RSCALE be the first item in an RRULE.
2. Added BYLEAPMONTH element and removed BYMONTH "L" suffix.
3. Removed Open Issues.
Daboo & Yakushev Expires September 16, 2014 [Page 13]
Internet-Draft iCalendar Property Extensions March 2014
Authors' Addresses
Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
Email: cyrus@daboo.name
URI: http://www.apple.com/
Gregory Yakushev
Google Inc.
Brandschenkestrasse 100
8002 Zurich,
Switzerland
Email: yakushev@google.com
URI: http://www.google.com/
Daboo & Yakushev Expires September 16, 2014 [Page 14]