idnits 2.17.1 draft-daboo-icalendar-rscale-01.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 (July 15, 2013) is 3928 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: January 16, 2014 July 15, 2013 8 Non-Gregorian Recurrence Rules in iCalendar 9 draft-daboo-icalendar-rscale-01 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 January 16, 2014. 33 Copyright Notice 35 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . 9 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 and Hebrew dates, respectively. 133 3. Overview 135 In the Gregorian calendar system, each year is composed of a fixed 136 number of months (12), with each month having a fixed number of days 137 (between 30 and 31), except for the second month (February) which 138 contains either 28 days, or 29 days (in a leap year). Weeks are 139 composed of 7 days, with day names Monday, Tuesday, Wednesday, 140 Thursday, Friday, Saturday and Sunday. Years can have either 365 or 141 366 days (the later in a leap year). The number of whole weeks in a 142 year is 52. 144 In iCalendar, the "RECUR" value type defines various fields used to 145 express a recurrence pattern, and those fields are given limits based 146 on those of the Gregorian calendar system. Since other calendar 147 systems can have different limits and other behaviors that need to be 148 accounted for, the maximum values for the elements in the "RECUR" 149 value are not covered by this specification. 151 To generate a set of recurring instances in a non-Gregorian calendar 152 system, the following procedure is used: 154 1. iCalendar data continues to use the "GREGORIAN" calendar system, 155 so all "DATE", "DATE-TIME" and "PERIOD" values continue to use 156 the Gregorian format and limits. 158 2. The "RRULE" property is extended to include an "RSCALE" element 159 in its value that specifies the calendar system to use for the 160 recurrence pattern. The existing elements of the "RRULE" value 161 type are used, but modified to support different upper limits, 162 based on the "RSCALE" value, as well as a modification to month 163 numbers to allow a leap month to be specified. Existing 164 requirements for the use of "RRULE" all still apply (e.g., the 165 "RRULE" has to match the "DTSTART" value of the master instance). 166 Other recurrence properties such as "RECURRENCE-ID", "RDATE" and 167 "EXDATE" continue to use the Gregorian date format as "CALSCALE" 168 is unchanged. 170 When generating instances, the following procedure might be used: 172 1. Convert the "DTSTART" property value of the master recurring 173 component into the date and time components for the calendar 174 system specified by the "RSCALE" element in the "RRULE" value. 175 This provides the "seed" value for generating subsequent 176 recurrence instances. 178 2. Iteratively generate instances using the "RRULE" value applied to 179 the year, month, and day components of the date in the new 180 calendar system. 182 3. For each generated instance, convert the date values back from 183 the non-Gregorian form into Gregorian and use those values for 184 other properties such as "RECURRENCE-ID". 186 Consider the following example for an event representing the Chinese 187 New Year: 189 DTSTART;VALUE=DATE:20130210 190 RRULE:RSCALE=CHINESE;FREQ=YEARLY 191 SUMMARY:Chinese New Year 193 To generate instances, first the "DTSTART" value "20130210" is 194 converted into the Chinese calendar system giving "{C}47110101". 195 Next, the year component is incremented by one to give "{C}47120101", 196 and that is then converted back into Gregorian as "20140131". 197 Additional instances are generated by iteratively increasing the year 198 component in the Chinese date value and converting back to Gregorian. 200 This specification makes use of calendar algorithms defined by the 201 Unicode Consortium [TBD - reference]. The definition of different 202 calendar scales is defined by Unicode, as per Section 5. 204 4. Extended RRULE Property 206 This specification extends the existing "RRULE" iCalendar property 207 value to include a new "RSCALE" element that can be used to indicate 208 the calendar system used for generating the recurrence pattern. 210 When "RSCALE" is present, the other changes to "RRULE" are: 212 1. Elements that include numeric values (e.g., "BYYEARDAY") have 213 numeric ranges defined by the "RSCALE" value (i.e., in some 214 calendar systems there might be more than 366 days in a year). 216 2. Month numbers can include an "L" suffix to indicate that the 217 specified month is a leap month in the corresponding calendar 218 system. 220 3. Month numbers can be specified using a negative offset (i.e., 221 "-1" represents the last month of the year). 223 4. A "SKIP" element is added to define how "missing" instances are 224 handled. e.g., if a yearly recurring event starts in a leap 225 month, the "SKIP" element determines whether instances in non- 226 leap years are ignored ("SKIP" set to "YES"), appear in the 227 preceding regular month ("SKIP" set to "BACKWARD" - the default 228 when "RSCALE" is present), or appear in the following regular 229 month ("SKIP" set to "FORWARD"). 231 The syntax for the "RECUR" value is modified in the following 232 fashion: 234 recur-rule-part /= ("RSCALE" "=" rscale) 235 / ("SKIP" "=" skip) 237 rscale = (iana-token ; A CLDR-registered calendar system 238 ; name. 239 / x-name) ; A non-standard, experimental 240 ; calendar system name. 242 skip = ("YES" / "BACKWARD" / "FORWARD") 243 ; When "RSCALE" is not present the default 244 ; is "YES". When "RSCALE" is present the default 245 ; is "BACKWARD". 247 monthnum = [plus / minus] 1*2DIGIT ["L"] 248 ; Existing element modified to include a positive 249 ; or negative offset capability, as well as a leap 250 ; month indicator suffix. 252 4.1. Handling Leap Months 254 Leap months can occur in different calendar systems. For most of 255 those, the suffix "L" is added to the "RRULE" month number component 256 to indicate a leap month. In some cases the month precedes the 257 regular month with the same number, in other cases it follows. The 258 one exception to this rule is the Hebrew calendar, where we follow 259 the definition from Unicode [TBD - REF]. In that case months are 260 number 1 through 13, with month 6 being the leap month. Thus in non- 261 leap years, month 6 is skipped. 263 4.2. Examples 265 4.2.1. Chinese New Year 267 Consider the following set of iCalendar properties: 269 DTSTART;VALUE=DATE:20130210 270 RRULE:RSCALE=CHINESE;FREQ=YEARLY 271 SUMMARY:Chinese New Year 273 These define a recurring event for the Chinese New Year, with the 274 first instance the one in Gregorian year 2013. 276 The Chinese date corresponding to the first instance is {C}47110101. 277 The table below shows the initial instance, and the next four, each 278 of which is determined by adding the appropriate amount to the year 279 component of the Chinese date. Also shown is the conversion back to 280 the Gregorian date: 282 +--------------+------------------------------------------------+ 283 | Chinese Date | Gregorian Date | 284 +--------------+------------------------------------------------+ 285 | {C}47110101 | 20130210 - DTSTART specified in iCalendar data | 286 | {C}47120101 | 20140131 | 287 | {C}47130101 | 20150120 | 288 | {C}47140101 | 20160208 | 289 | {C}47150101 | 20170128 | 290 +--------------+------------------------------------------------+ 292 4.2.2. Islamic Start of Ramadan 294 Consider the following set of iCalendar properties: 296 DTSTART;VALUE=DATE:20130709 297 RRULE:RSCALE=ISLAMIC;FREQ=YEARLY;BYMONTH=9 298 SUMMARY:Start of Ramadan 299 These define a recurring event for the start of the Islamic month of 300 Ramadan, with the first instance the one in Gregorian year 2013. 302 The Islamic date corresponding to the first instance is {I}14340901. 303 The table below shows the initial instance, and the next four, each 304 of which is determined by adding the appropriate amount to the year 305 component of the Islamic date. Also shown is the conversion back to 306 the Gregorian date: 308 +--------------+------------------------------------------------+ 309 | Islamic Date | Gregorian Date | 310 +--------------+------------------------------------------------+ 311 | {I}14340901 | 20130709 - DTSTART specified in iCalendar data | 312 | {I}14350901 | 20140628 | 313 | {I}14360901 | 20150618 | 314 | {I}14370901 | 20160606 | 315 | {I}14380901 | 20170527 | 316 +--------------+------------------------------------------------+ 318 Note that in this example, the value of the "BYMONTH" component in 319 the "RRULE" matches the Islamic month value and not the Gregorian 320 month. 322 4.2.3. Hebrew anniversary starting in a leap month 324 Consider the following set of iCalendar properties: 326 DTSTART;VALUE=DATE:20140208 327 RRULE:RSCALE=HEBREW;FREQ=YEARLY;BYMONTH=6;BYMONTHDAY=8;SKIP=FORWARD 328 SUMMARY:Anniversary 330 These define a recurring event for the 8th day of the Hebrew month of 331 Adar I, with the first instance the one in Gregorian year 2014. 333 The Hebrew date corresponding to the first instance is {H}57740608, 334 note that month 6 is a leap month in year 5774. The table below 335 shows the initial instance, and the next four, each of which is 336 determined by adding the appropriate amount to the year component of 337 the Hebrew date, taking into account that only year 5776 is a leap 338 year. Thus in other years the Hebrew month component is adjusted 339 forward to month 7. Also shown is the conversion back to the 340 Gregorian date: 342 +-------------+------------------------------------------------+ 343 | Hebrew Date | Gregorian Date | 344 +-------------+------------------------------------------------+ 345 | {H}57740608 | 20140208 - DTSTART specified in iCalendar data | 346 | {H}57750708 | 20150227 | 347 | {H}57760608 | 20160217 | 348 | {H}57770708 | 20170306 | 349 | {H}57780708 | 20180223 | 350 +-------------+------------------------------------------------+ 352 5. Registering Calendar Systems 354 This specification uses the Unicode Consortium's registry of calendar 355 systems to define valid values for the "RSCALE" element of an "RRULE" 356 [TBD - Unicode BCP47 - 357 http://unicode.org/repos/cldr/trunk/common/bcp47/calendar.xml]. Note 358 that the underscore character "_" is never used in CLDR-based 359 calendar system names. New values can be added to this registry 360 following Unicode Consortium rules. It is expected that many 361 implementations of non-Gregorian calendars will use software 362 libraries provided by Unicode (ICU), and hence it makes sense to re- 363 use their registry rather than creating a new one. For consistency, 364 when used, the "RSCALE" values SHOULD be uppercased. 366 6. Security Considerations 368 This specification does not introduce any addition security concerns 369 beyond those described in [RFC5545]. 371 7. IANA Considerations 373 This specification does not define any new IANA registries or values. 375 8. Acknowledgments 377 Thanks to the following for feedback: Mark Davis, Mike Douglass, 378 Peter Edberg, Arnaud Quillaud, and Dave Thewlis. This specification 379 came about via discussions at the Calendaring and Scheduling 380 Consortium. 382 9. Normative References 384 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 385 Requirement Levels", BCP 14, RFC 2119, March 1997. 387 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 388 Specifications: ABNF", STD 68, RFC 5234, January 2008. 390 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling 391 Core Object Specification (iCalendar)", RFC 5545, 392 September 2009. 394 Appendix A. Change History (To be removed by RFC Editor before 395 publication) 397 Changes in -01: 399 1. Removed requirement that RSCALE be the first item in an RRULE. 401 2. Added BYLEAPMONTH element and removed BYMONTH "L" suffix. 403 3. Removed OpPen Issues. 405 Authors' Addresses 407 Cyrus Daboo 408 Apple Inc. 409 1 Infinite Loop 410 Cupertino, CA 95014 411 USA 413 Email: cyrus@daboo.name 414 URI: http://www.apple.com/ 416 Gregory Yakushev 417 Google Inc. 418 Brandschenkestrasse 100 419 8002 Zurich, 420 Switzerland 422 Email: yakushev@google.com 423 URI: http://www.google.com/