idnits 2.17.1 draft-daboo-icalendar-rscale-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC5545, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC5545, updated by this document, for RFC5378 checks: 2005-10-26) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 7, 2014) is 3763 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft Apple Inc. 4 Updates: 5545 (if approved) G. Yakushev 5 Intended status: Standards Track Google Inc. 6 Expires: July 11, 2014 January 7, 2014 8 Non-Gregorian Recurrence Rules in iCalendar 9 draft-daboo-icalendar-rscale-02 11 Abstract 13 This document defines how non-Gregorian recurrence rules can be 14 specified in iCalendar data. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on July 11, 2014. 33 Copyright Notice 35 Copyright (c) 2014 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 52 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 4. Extended RRULE Property . . . . . . . . . . . . . . . . . . . 6 54 4.1. Handling Leap Months . . . . . . . . . . . . . . . . . . . 7 55 4.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7 56 5. Registering Calendar Systems . . . . . . . . . . . . . . . . . 9 57 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 58 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 59 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 60 9. Normative References . . . . . . . . . . . . . . . . . . . . . 10 61 Appendix A. Change History (To be removed by RFC Editor 62 before publication) . . . . . . . . . . . . . . . . . 10 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 65 1. Introduction 67 The iCalendar [RFC5545] data format is in widespread use to represent 68 calendar data. iCalendar represents dates and times using the 69 Gregorian calendar system only. It does provide a way to use non- 70 Gregorian calendar systems via a "CALSCALE" property, however this 71 has never been formally used. However, there is a need to support at 72 least non-Gregorian recurrence patterns to cover anniversaries, and 73 many local, religious, or civil holidays based on non-Gregorian 74 dates. 76 There are several disadvantages to using the existing "CALSCALE" 77 property in iCalendar for implementing non-Gregorian calendars: 79 1. The "CALSCALE" property exists in the top-level "VCALENDAR" 80 objects and thus applies to all components within that object. 81 In today's multi-cultural society, that restricts the ability to 82 mix events from different calendar systems within the same 83 iCalendar object. e.g., it would prevent having both the 84 Gregorian New Year and Chinese New Year in the same iCalendar 85 object. 87 2. Many countries observe daylight savings time, encoded in 88 iCalendar using the "VTIMEZONE" component. Timezone and daylight 89 saving time rules are always specified via Gregorian calendar 90 based recurrence rules (e.g., "the 3rd Sunday in March"). This 91 is problematic for non-Gregorian uses of "CALSCALE" which would 92 by default also apply to the dates and rules used in the 93 "VTIMEZONE" components in the corresponding iCalendar object. 95 This specification solves these issues by allowing the "CALSCALE" to 96 remain set to Gregorian, but re-defining the recurrence rule property 97 "RRULE" to accept new items including one that allows non-Gregorian 98 calendar systems to be used. With this, all the date, time and 99 period values in the iCalendar object would remain specified using 100 the Gregorian calendar system, but repeating patterns in other 101 calendar systems could be defined. It is then up to calendar user 102 agents and servers to map between Gregorian and non-Gregorian 103 calendar systems in order to expand out recurrence instances. 105 This specification does not itself define calendar systems, rather it 106 utilizes the registry defined by the Unicode Consortium 107 (http://unicode.org) in their CLDR (Common Locale Data Repository) 108 project. 110 2. Conventions Used in This Document 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in 115 [RFC2119]. 117 The notation used in this memo is the ABNF notation of [RFC5234] as 118 used by iCalendar [RFC5545]. Any syntax elements shown below that 119 are not explicitly defined in this specification come from iCalendar 120 [RFC5545]. 122 When a Gregorian calendar date value is shown in text, it will use 123 the format "YYYYMMHH", where "YYYY" is the 4-digit year, "MM" the 124 2-digit month, and "DD" the 2-digit day (this is the same format used 125 in iCalendar [RFC5545]). The Chinese calendar will be used as an 126 example of a non-Gregorian calendar for illustrative purposes. When 127 a Chinese calendar date value is shown in text, it will use the 128 format "{C}YYYYMM[L]DD" - i.e., the same format as Gregorian but with 129 a "{C}" prefix, and an optional "L" character after the month element 130 to indicate a leap month. Similarly, {I} and {H} are used in other 131 examples as prefixes for Islamic (Civil) and Hebrew dates, 132 respectively. 134 3. Overview 136 In the Gregorian calendar system, each year is composed of a fixed 137 number of months (12), with each month having a fixed number of days 138 (between 30 and 31), except for the second month (February) which 139 contains either 28 days, or 29 days (in a leap year). Weeks are 140 composed of 7 days, with day names Monday, Tuesday, Wednesday, 141 Thursday, Friday, Saturday and Sunday. Years can have either 365 or 142 366 days (the later in a leap year). The number of whole weeks in a 143 year is 52. 145 In iCalendar, the "RECUR" value type defines various fields used to 146 express a recurrence pattern, and those fields are given limits based 147 on those of the Gregorian calendar system. Since other calendar 148 systems can have different limits and other behaviors that need to be 149 accounted for, the maximum values for the elements in the "RECUR" 150 value are not covered by this specification. 152 To generate a set of recurring instances in a non-Gregorian calendar 153 system, the following procedure is used: 155 1. iCalendar data continues to use the "GREGORIAN" calendar system, 156 so all "DATE", "DATE-TIME" and "PERIOD" values continue to use 157 the Gregorian format and limits. 159 2. The "RRULE" property is extended to include an "RSCALE" element 160 in its value that specifies the calendar system to use for the 161 recurrence pattern. The existing elements of the "RRULE" value 162 type are used, but modified to support different upper limits, 163 based on the "RSCALE" value, as well as a modification to month 164 numbers to allow a leap month to be specified. Existing 165 requirements for the use of "RRULE" all still apply (e.g., the 166 "RRULE" has to match the "DTSTART" value of the master instance). 167 Other recurrence properties such as "RECURRENCE-ID", "RDATE" and 168 "EXDATE" continue to use the Gregorian date format as "CALSCALE" 169 is unchanged. 171 When generating instances, the following procedure might be used: 173 1. Convert the "DTSTART" property value of the master recurring 174 component into the date and time components for the calendar 175 system specified by the "RSCALE" element in the "RRULE" value. 176 This provides the "seed" value for generating subsequent 177 recurrence instances. 179 2. Iteratively generate instances using the "RRULE" value applied to 180 the year, month, and day components of the date in the new 181 calendar system. 183 3. For each generated instance, convert the date values back from 184 the non-Gregorian form into Gregorian and use those values for 185 other properties such as "RECURRENCE-ID". 187 Consider the following example for an event representing the Chinese 188 New Year: 190 DTSTART;VALUE=DATE:20130210 191 RRULE:RSCALE=CHINESE;FREQ=YEARLY 192 SUMMARY:Chinese New Year 194 To generate instances, first the "DTSTART" value "20130210" is 195 converted into the Chinese calendar system giving "{C}47110101". 196 Next, the year component is incremented by one to give "{C}47120101", 197 and that is then converted back into Gregorian as "20140131". 198 Additional instances are generated by iteratively increasing the year 199 component in the Chinese date value and converting back to Gregorian. 201 This specification makes use of calendar algorithms defined by the 202 Unicode Consortium [TBD - reference]. The definition of different 203 calendar scales is defined by Unicode, as per Section 5. 205 4. Extended RRULE Property 207 This specification extends the existing "RRULE" iCalendar property 208 value to include a new "RSCALE" element that can be used to indicate 209 the calendar system used for generating the recurrence pattern. 211 When "RSCALE" is present, the other changes to "RRULE" are: 213 1. Elements that include numeric values (e.g., "BYYEARDAY") have 214 numeric ranges defined by the "RSCALE" value (i.e., in some 215 calendar systems there might be more than 366 days in a year). 217 2. Month numbers can include an "L" suffix to indicate that the 218 specified month is a leap month in the corresponding calendar 219 system. 221 3. Month numbers can be specified using a negative offset (i.e., 222 "-1" represents the last month of the year). 224 4. A "SKIP" element is added to define how "missing" instances are 225 handled. e.g., if a yearly recurring event starts in a leap 226 month, the "SKIP" element determines whether instances in non- 227 leap years are ignored ("SKIP" set to "YES"), appear in the 228 preceding regular month ("SKIP" set to "BACKWARD" - the default 229 when "RSCALE" is present), or appear in the following regular 230 month ("SKIP" set to "FORWARD"). The "SKIP" processing is done 231 after all other rule elements except for "COUNT" and "UNTIL" have 232 been processed. 234 The syntax for the "RECUR" value is modified in the following 235 fashion: 237 recur-rule-part /= ("RSCALE" "=" rscale) 238 / ("SKIP" "=" skip) 240 rscale = (iana-token ; A CLDR-registered calendar system 241 ; name. 242 / x-name) ; A non-standard, experimental 243 ; calendar system name. 245 skip = ("YES" / "BACKWARD" / "FORWARD") 246 ; When "RSCALE" is not present the default 247 ; is "YES". When "RSCALE" is present the default 248 ; is "BACKWARD". 250 monthnum = [plus / minus] 1*2DIGIT ["L"] 251 ; Existing element modified to include a positive 252 ; or negative offset capability, as well as a leap 253 ; month indicator suffix. 255 4.1. Handling Leap Months 257 Leap months can occur in different calendar systems. For most of 258 those, the suffix "L" is added to the "RRULE" month number component 259 to indicate a leap month. In some cases the month precedes the 260 regular month with the same number, in other cases it follows. The 261 one exception to this rule is the Hebrew calendar, where we follow 262 the definition from Unicode [TBD - REF]. In that case months are 263 number 1 through 13, with month 6 being the leap month. Thus in non- 264 leap years, month 6 is skipped. 266 4.2. Examples 268 4.2.1. Chinese New Year 270 Consider the following set of iCalendar properties: 272 DTSTART;VALUE=DATE:20130210 273 RRULE:RSCALE=CHINESE;FREQ=YEARLY 274 SUMMARY:Chinese New Year 276 These define a recurring event for the Chinese New Year, with the 277 first instance the one in Gregorian year 2013. 279 The Chinese date corresponding to the first instance is {C}47110101. 280 The table below shows the initial instance, and the next four, each 281 of which is determined by adding the appropriate amount to the year 282 component of the Chinese date. Also shown is the conversion back to 283 the Gregorian date: 285 +--------------+------------------------------------------------+ 286 | Chinese Date | Gregorian Date | 287 +--------------+------------------------------------------------+ 288 | {C}47110101 | 20130210 - DTSTART specified in iCalendar data | 289 | {C}47120101 | 20140131 | 290 | {C}47130101 | 20150219 | 291 | {C}47140101 | 20160208 | 292 | {C}47150101 | 20170128 | 293 +--------------+------------------------------------------------+ 295 4.2.2. Islamic Civil Start of Ramadan 297 Consider the following set of iCalendar properties: 299 DTSTART;VALUE=DATE:20130709 300 RRULE:RSCALE=ISLAMIC-CIVIL;FREQ=YEARLY;BYMONTH=9 301 SUMMARY:Start of Ramadan 303 These define a recurring event for the start of the Islamic month of 304 Ramadan, with the first instance the one in Gregorian year 2013. 306 The Islamic date corresponding to the first instance is {I}14340901. 307 The table below shows the initial instance, and the next four, each 308 of which is determined by adding the appropriate amount to the year 309 component of the Islamic date. Also shown is the conversion back to 310 the Gregorian date: 312 +--------------+------------------------------------------------+ 313 | Islamic Date | Gregorian Date | 314 +--------------+------------------------------------------------+ 315 | {I}14340901 | 20130709 - DTSTART specified in iCalendar data | 316 | {I}14350901 | 20140629 | 317 | {I}14360901 | 20150618 | 318 | {I}14370901 | 20160607 | 319 | {I}14380901 | 20170527 | 320 +--------------+------------------------------------------------+ 322 Note that in this example, the value of the "BYMONTH" component in 323 the "RRULE" matches the Islamic month value and not the Gregorian 324 month. 326 4.2.3. Hebrew anniversary starting in a leap month 328 Consider the following set of iCalendar properties: 330 DTSTART;VALUE=DATE:20140208 331 RRULE:RSCALE=HEBREW;FREQ=YEARLY;BYMONTH=6;BYMONTHDAY=8;SKIP=FORWARD 332 SUMMARY:Anniversary 334 These define a recurring event for the 8th day of the Hebrew month of 335 Adar I, with the first instance the one in Gregorian year 2014. 337 The Hebrew date corresponding to the first instance is {H}57740608, 338 note that month 6 is a leap month in year 5774. The table below 339 shows the initial instance, and the next four, each of which is 340 determined by adding the appropriate amount to the year component of 341 the Hebrew date, taking into account that only year 5776 is a leap 342 year. Thus in other years the Hebrew month component is adjusted 343 forward to month 7. Also shown is the conversion back to the 344 Gregorian date: 346 +-------------+------------------------------------------------+ 347 | Hebrew Date | Gregorian Date | 348 +-------------+------------------------------------------------+ 349 | {H}57740608 | 20140208 - DTSTART specified in iCalendar data | 350 | {H}57750708 | 20150227 | 351 | {H}57760608 | 20160217 | 352 | {H}57770708 | 20170306 | 353 | {H}57780708 | 20180223 | 354 +-------------+------------------------------------------------+ 356 5. Registering Calendar Systems 358 This specification uses the Unicode Consortium's registry of calendar 359 systems [UNICODE.CLDR] to define valid values for the "RSCALE" 360 element of an "RRULE". Note that the underscore character "_" is 361 never used in CLDR-based calendar system names. New values can be 362 added to this registry following Unicode Consortium rules. It is 363 expected that many implementations of non-Gregorian calendars will 364 use software libraries provided by Unicode (ICU), and hence it makes 365 sense to re-use their registry rather than creating a new one. For 366 consistency, when used, the "RSCALE" values SHOULD be uppercased. 368 CLDR supports the use of "alias" values as alternative names for 369 specific calendar systems. These alias values MUST be treated as 370 valid "RSCALE" element values. 372 When using the CLDR data, calendar agents SHOULD take into account 373 the "deprecated" value and use the alternative "preferred" calendar 374 system. In particular, the "islamicc" calendar system is considered 375 deprecated in favor of the "islamic-civil" calendar system. 377 6. Security Considerations 379 This specification does not introduce any addition security concerns 380 beyond those described in [RFC5545]. 382 7. IANA Considerations 384 This specification does not define any new IANA registries or values. 386 8. Acknowledgments 388 Thanks to the following for feedback: Mark Davis, Mike Douglass, 389 Peter Edberg, Arnaud Quillaud, and Dave Thewlis. This specification 390 came about via discussions at the Calendaring and Scheduling 391 Consortium. 393 9. Normative References 395 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 396 Requirement Levels", BCP 14, RFC 2119, March 1997. 398 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 399 Specifications: ABNF", STD 68, RFC 5234, January 2008. 401 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling 402 Core Object Specification (iCalendar)", RFC 5545, 403 September 2009. 405 [UNICODE.CLDR] 406 "CLDR calendar.xml Data", Unicode Consortium CLDR, 407 August 2013, . 410 Appendix A. Change History (To be removed by RFC Editor before 411 publication) 413 Changes in -02: 415 1. Fixed some incorrect dates in examples. 417 2. Clarified use of CLDR and alias, deprecated, preferred 418 attributes. 420 3. Clarified when SKIP processing occurs. 422 Changes in -01: 424 1. Removed requirement that RSCALE be the first item in an RRULE. 426 2. Added BYLEAPMONTH element and removed BYMONTH "L" suffix. 428 3. Removed Open Issues. 430 Authors' Addresses 432 Cyrus Daboo 433 Apple Inc. 434 1 Infinite Loop 435 Cupertino, CA 95014 436 USA 438 Email: cyrus@daboo.name 439 URI: http://www.apple.com/ 441 Gregory Yakushev 442 Google Inc. 443 Brandschenkestrasse 100 444 8002 Zurich, 445 Switzerland 447 Email: yakushev@google.com 448 URI: http://www.google.com/