Non-Gregorian Recurrence Rules in iCalendar
draft-daboo-icalendar-rscale-01

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 January 16, 2014.

Copyright Notice

Copyright (c) 2013 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.

Table of Contents

• 1. Introduction
• 2. Conventions Used in This Document
• 3. Overview
• 4. Extended RRULE Property
• 4.1. Handling Leap Months
• 4.2. Examples
• 5. Registering Calendar Systems
• 6. Security Considerations
• 7. IANA Considerations
• 8. Acknowledgments
• 9. Normative References
• Appendix A. Change History (To be removed by RFC Editor before publication)
• Authors' Addresses

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.

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].

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 and Hebrew dates, respectively.

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 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".

DTSTART;VALUE=DATE:20130210
RRULE:RSCALE=CHINESE;FREQ=YEARLY
SUMMARY:Chinese New Year

Consider the following example for an event representing the Chinese New Year:

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").

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.

The syntax for the "RECUR" value is modified in the following fashion:

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

DTSTART;VALUE=DATE:20130210
RRULE:RSCALE=CHINESE;FREQ=YEARLY
SUMMARY:Chinese New Year

Consider the following set of iCalendar properties:

The Chinese date corresponding to the first instance is {C}47110101. 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:

4.2.2. Islamic Start of Ramadan

DTSTART;VALUE=DATE:20130709
RRULE:RSCALE=ISLAMIC;FREQ=YEARLY;BYMONTH=9
SUMMARY:Start of Ramadan

Consider the following set of iCalendar properties:

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:

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

DTSTART;VALUE=DATE:20140208
RRULE:RSCALE=HEBREW;FREQ=YEARLY;BYMONTH=6;BYMONTHDAY=8;SKIP=FORWARD
SUMMARY:Anniversary

Consider the following set of iCalendar properties:

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:

5. Registering Calendar Systems

This specification uses the Unicode Consortium's registry of calendar systems to define valid values for the "RSCALE" element of an "RRULE" [TBD - Unicode BCP47 - http://unicode.org/repos/cldr/trunk/common/bcp47/calendar.xml]. 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.

6. Security Considerations

This specification does not introduce any addition security concerns beyond those described in [RFC5545].

7. IANA Considerations

This specification does not define any new IANA registries or values.

8. 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.

9. Normative References

Appendix A. Change History (To be removed by RFC Editor before publication)

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 OpPen Issues.

Authors' Addresses