idnits 2.17.1 draft-daboo-icalendar-extensions-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 26, 2010) is 5173 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: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). 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 Intended status: Standards Track February 26, 2010 5 Expires: August 30, 2010 7 New Properties for iCalendar 8 draft-daboo-icalendar-extensions-00 10 Abstract 12 This document defines a set of new properties for iCalendar data. 14 Status of this Memo 16 This Internet-Draft is submitted to IETF in full conformance with the 17 provisions of BCP 78 and BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on August 30, 2010. 37 Copyright Notice 39 Copyright (c) 2010 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 56 3. Modifications to Calendar Components . . . . . . . . . . . . . 3 57 4. Calendar Properties . . . . . . . . . . . . . . . . . . . . . 5 58 4.1. CALENDAR-NAME Property . . . . . . . . . . . . . . . . . . 5 59 4.2. CALENDAR-DESCRIPTION Property . . . . . . . . . . . . . . 6 60 4.3. CALENDAR-UID Property . . . . . . . . . . . . . . . . . . 7 61 4.4. CALENDAR-URL Property . . . . . . . . . . . . . . . . . . 7 62 4.5. CALENDAR-TZID Property . . . . . . . . . . . . . . . . . . 8 63 4.6. CALENDAR-REFRESH-INTERVAL Property . . . . . . . . . . . . 9 64 4.7. CALENDAR-COLOR Property . . . . . . . . . . . . . . . . . 9 65 4.8. CALENDAR-IMAGE Property . . . . . . . . . . . . . . . . . 10 66 5. Component Properties . . . . . . . . . . . . . . . . . . . . . 12 67 5.1. IMAGE Property . . . . . . . . . . . . . . . . . . . . . . 12 68 6. Property Parameters . . . . . . . . . . . . . . . . . . . . . 13 69 6.1. DISPLAY Property Parameter . . . . . . . . . . . . . . . . 13 70 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 71 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 72 8.1. Property Registrations . . . . . . . . . . . . . . . . . . 14 73 8.2. Paramater Registrations . . . . . . . . . . . . . . . . . 15 74 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 75 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 76 10.1. Normative References . . . . . . . . . . . . . . . . . . . 15 77 10.2. Informative References . . . . . . . . . . . . . . . . . . 16 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 80 1. Introduction 82 The iCalendar [RFC5545] data format is used to represent calendar 83 data and is used with iTIP [RFC5546] to handle scheduling operations 84 between calendar users. iCalendar is in widespread use, and in 85 accordance with provisions in that specification, extension elements 86 have been added by various vendors to the data format in order to 87 support and enhance capabilities. This specification collates a 88 number of these ad-hoc extensions and uses the new IANA registry 89 capability defined in [RFC5545] to register standard variants with 90 clearly defined definitions and semantics. In addition, some new 91 elements are introduced for features that vendors have been 92 requesting recently. 94 2. Conventions Used in This Document 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 98 "OPTIONAL" in this document are to be interpreted as described in 99 [RFC2119]. 101 The notation used in this memo is the ABNF notation of [RFC5234] as 102 used by iCalendar [RFC5545]. Any syntax elements shown below that 103 are not explicitly defined in this specification come from iCalendar 104 [RFC5545]. 106 3. Modifications to Calendar Components 108 The following changes to the syntax defined in iCalendar [RFC5545] 109 are made here. New elements are defined in subsequent sections. 111 calprops /= *( 112 ; 113 ; The following are OPTIONAL, 114 ; but MUST NOT occur more than once. 115 ; 116 calname / caldescription / 117 caluid / calurl / caltzid / 118 calrefresh / calcolor / 119 ; 120 ; The following are OPTIONAL, 121 ; and MAY occur more than once. 122 ; 123 calimg 124 ; 125 ) 127 eventprop /= *( 128 ; 129 ; The following are OPTIONAL, 130 ; and MAY occur more than once. 131 ; 132 image 133 ; 134 ) 136 todoprop /= *( 137 ; 138 ; The following are OPTIONAL, 139 ; and MAY occur more than once. 140 ; 141 image 142 ; 143 ) 145 jourprop /= *( 146 ; 147 ; The following are OPTIONAL, 148 ; and MAY occur more than once. 149 ; 150 image 151 ; 152 ) 154 4. Calendar Properties 156 4.1. CALENDAR-NAME Property 158 Property Name: CALENDAR-NAME 160 Purpose: This property specifies the name of the calendar. 162 Value Type: TEXT 164 Property Parameters: IANA, non-standard, alternate text 165 representation, and language property parameters can be specified 166 on this property. 168 Conformance: This property can be specified once in an iCalendar 169 object. 171 Description: This property is used to specify a name (a short, one- 172 line description) of the iCalendar object that can be used by 173 calendar user agents when presenting the calendar data to a user. 175 Format Definition: This property is defined by the following 176 notation: 178 calname = "CALENDAR-NAME" calnameparam ":" text CRLF 180 calnameparam = *( 181 ; 182 ; The following are OPTIONAL, 183 ; but MUST NOT occur more than once. 184 ; 185 (";" altrepparam) / (";" languageparam) / 186 ; 187 ; The following is OPTIONAL, 188 ; and MAY occur more than once. 189 ; 190 (";" other-param) 191 ; 192 ) 194 Example: The following is an example of this property: 196 CALENDAR-NAME:Company Vacation Days 198 4.2. CALENDAR-DESCRIPTION Property 200 Property Name: CALENDAR-DESCRIPTION 202 Purpose: This property specifies the description of the calendar. 204 Value Type: TEXT 206 Property Parameters: IANA, non-standard, alternate text 207 representation, and language property parameters can be specified 208 on this property. 210 Conformance: This property can be specified once in an iCalendar 211 object. 213 Description: This property is used to specify a lengthy textual 214 description of the iCalendar object that can be used by calendar 215 user agents when describing the nature of the calendar data to a 216 user. 218 Format Definition: This property is defined by the following 219 notation: 221 caldesc = "CALENDAR-DESCRIPTION" caldescparam ":" text 222 CRLF 224 caldescparam = *( 225 ; 226 ; The following are OPTIONAL, 227 ; but MUST NOT occur more than once. 228 ; 229 (";" altrepparam) / (";" languageparam) / 230 ; 231 ; The following is OPTIONAL, 232 ; and MAY occur more than once. 233 ; 234 (";" other-param) 235 ; 236 ) 238 Example: The following is an example of this property: 240 CALENDAR-DESCRIPTION:This calendar contains all the \ 241 official vacation days of our company.\nThese repre\ 242 sent paid time-off - make sure you have fun, we'll \ 243 be working you hard on the other days! 245 4.3. CALENDAR-UID Property 247 Property Name: CALENDAR-UID 249 Purpose: This property specifies the persistent, globally unique 250 identifier for the calendar. 252 Value Type: TEXT 254 Property Parameters: IANA and non-standard property parameters can 255 be specified on this property. 257 Conformance: This property can be specified once in an iCalendar 258 object. 260 Description: The value of this property MUST be a globally unique 261 identifier. The generator of the property MUST guarantee that the 262 value is unique. This can be done following the recommendations 263 in Section 3.8.4.7 of [RFC5545]. Implementations MUST be able to 264 receive and persist values of at least 255 octets for this 265 property, but they MUST NOT truncate values in the middle of a 266 UTF-8 multi-octet sequence. 268 Format Definition: This property is defined by the following 269 notation: 271 caluid = "CALENDAR-UID" caluidparam ":" text CRLF 273 caluidparam = *(";" other-param) 275 Example: The following is an example of this property: 277 CALENDAR-UID:19960401T080045Z-4000F192713-0052@example.com 279 4.4. CALENDAR-URL Property 281 Property Name: CALENDAR-URL 283 Purpose: This property specifies a URL from where the calendar data 284 was retrieved or where it can be refreshed. 286 Value Type: URI 288 Property Parameters: IANA and non-standard property parameters can 289 be specified on this property. 291 Conformance: This property can be specified once in an iCalendar 292 object. 294 Description: This property specifies a URL identifying the source of 295 the calendar data and a location from where updates can be 296 retrieved. 298 Format Definition: This property is defined by the following 299 notation: 301 calurl = "CALENDAR-URL" calurlparam ":" url CRLF 303 calurlparam = *(";" other-param) 305 Example: The following is an example of this property: 307 CALENDAR-URL:http://calendars.example.com/holidays/canada.ics 309 4.5. CALENDAR-TZID Property 311 Property Name: CALENDAR-TZID 313 Purpose: This property specifies the default time zone identifier 314 for the calendar. 316 Value Type: TEXT 318 Property Parameters: IANA and non-standard property parameters can 319 be specified on this property. 321 Conformance: This property can be specified once in an iCalendar 322 object. 324 Description: This property specifies a time zone identifier that 325 represents the default timezone for which floating time or all-day 326 events in the iCalendar object can be assumed to be relative to. 327 It can also be used to choose an initial time zone for use when 328 creating new components in the iCalendar object. A "VTIMEZONE" 329 component having a "TZID" property matching the value specified in 330 this property MUST be present in the iCalendar object. 332 Format Definition: This property is defined by the following 333 notation: 335 caltzid = "CALENDAR-TZID" caltzidparam ":" [tzidprefix] 336 text CRLF 338 caltzidparam = *(";" other-param) 340 Example: The following is an example of this property: 342 CALENDAR-TZID:America/New_York 344 4.6. CALENDAR-REFRESH-INTERVAL Property 346 Property Name: CALENDAR-REFRESH-INTERVAL 348 Purpose: This property specifies a suggested interval for polling 349 for changes of the calendar data from the original source of that 350 data. 352 Value Type: DURATION 354 Property Parameters: IANA and non-standard property parameters can 355 be specified on this property. 357 Conformance: This property can be specified once in an iCalendar 358 object. 360 Description: This property specifies a positive duration that gives 361 a suggested polling interval for checking for updates to the 362 calendar data. The value of this property SHOULD be used by 363 calendar user agents as the polling interval for calendar data 364 updates. 366 Format Definition: This property is defined by the following 367 notation: 369 calrefesh = "CALENDAR-REFRESH-INTERVAL" calrefreshparam 370 ":" dur-value CRLF 371 ;consisting of a positive duration of time. 373 calrefeshparam = *(";" other-param) 375 Example: The following is an example of this property: 377 CALENDAR-REFRESH-INTERVAL:P1W 379 4.7. CALENDAR-COLOR Property 381 Property Name: CALENDAR-COLOR 383 Purpose: This property specifies a color used for displaying the 384 calendar data. 386 Value Type: INTEGER. The value MUST be three SEMICOLON-separated 387 INTEGER values. 389 Property Parameters: IANA and non-standard property parameters can 390 be specified on this property. 392 Conformance: This property can be specified once in an iCalendar 393 object. 395 Description: This property specifies a color that client MAY use 396 when presenting the calendar data to a user. Typically this would 397 appear as the "background" color of events or tasks. The value 398 MUST be an RGB value with integer value components in the range 399 0..255 401 Format Definition: This property is defined by the following 402 notation: 404 calcolor = "CALENDAR-COLOR" calcolorparam ":" 405 calcolorvalue CRLF 407 calcolorparam = *(";" other-param) 409 calcolorvalue = integer ";" integer ";" integer 410 ; Red, green, and blue values in the range 411 ; 0 - 255. 413 Example: The following is an example of this property: 415 CALENDAR-COLOR:255;0;255 417 4.8. CALENDAR-IMAGE Property 419 Property Name: CALENDAR-IMAGE 421 Purpose: This property specifies an image associated with the 422 calendar. 424 Value Type: The default value type for this property is URI. The 425 value type can also be set to BINARY to indicate inline binary 426 encoded content information. The value MUST refer to or be data 427 with a media type of "image". 429 Property Parameters: IANA, non-standard, display, inline encoding, 430 and value data type property parameters can be specified on this 431 property. The format type parameter can be specified on this 432 property and is RECOMMENDED for inline binary encoded content 433 information. 435 Conformance: This property can be specified multiple times in an 436 iCalendar object. 438 Description: This property specifies an image for an iCalendar 439 object via a uri or directly with inline data that can be used by 440 calendar user agents when presenting the calendar data to a user. 441 Multiple properties MAY be used to specify alternative sets of 442 images with, for example, varying media subtypes, resolutions or 443 sizes. When multiple properties are present, calendar user agents 444 SHOULD display only one of them, picking one that provides the 445 most appropriate image quality, or display none. The "DISPLAY" 446 parameter is used to indicate the intended display mode for the 447 image. 449 Format Definition: This property is defined by the following 450 notation: 452 calimg = "CALENDAR-IMAGE" calimgparam ( ":" uri ) / 453 ( 454 ";" "ENCODING" "=" "BASE64" 455 ";" "VALUE" "=" "BINARY" 456 ":" binary 457 ) 458 CRLF 460 calimgparam = *( 461 ; 462 ; The following is OPTIONAL for a URI value, 463 ; RECOMMENDED for a BINARY value, 464 ; and MUST NOT occur more than once. 465 ; 466 (";" fmttypeparam) / 467 ; 468 ; The following is OPTIONAL, 469 ; and MOST NOT occur more than once. 470 ; 471 (";" displayparam) 472 ; 473 ; The following is OPTIONAL, 474 ; and MAY occur more than once. 475 ; 476 (";" other-param) 477 ; 478 ) 480 Example: The following is an example of this property: 482 CALENDAR-IMAGE;DISPLAY=BADGE;FMTTYPE=image/png:http://ex 483 ample.com/images/holiday.png 485 5. Component Properties 487 5.1. IMAGE Property 489 Property Name: IMAGE 491 Purpose: This property specifies an image associated with the 492 calendar. 494 Value Type: The default value type for this property is URI. The 495 value type can also be set to BINARY to indicate inline binary 496 encoded content information. The value MUST refer to or be data 497 with a media type of "image". 499 Property Parameters: IANA, non-standard, display, inline encoding, 500 and value data type property parameters can be specified on this 501 property. The format type parameter can be specified on this 502 property and is RECOMMENDED for inline binary encoded content 503 information. 505 Conformance: This property can be specified multiple times in a 506 "VEVENT", "VTODO", or "VJOURNAL" calendar component. 508 Description: This property specifies an image for a calendar 509 component via a uri or directly with inline data that can be used 510 by calendar user agents when presenting the calendar data to a 511 user. Multiple properties MAY be used to specify alternative sets 512 of images with, for example, varying media subtypes, resolutions 513 or sizes. When multiple properties are present, calendar user 514 agents SHOULD display only one of them, picking one that provides 515 the most appropriate image quality, or display none. The 516 "DISPLAY" parameter is used to indicate the intended display mode 517 for the image. 519 Format Definition: This property is defined by the following 520 notation: 522 image = "IMAGE" imageparam ( ":" uri ) / 523 ( 524 ";" "ENCODING" "=" "BASE64" 525 ";" "VALUE" "=" "BINARY" 526 ":" binary 527 ) 528 CRLF 530 imageparam = *( 531 ; 532 ; The following is OPTIONAL for a URI value, 533 ; RECOMMENDED for a BINARY value, 534 ; and MUST NOT occur more than once. 535 ; 536 (";" fmttypeparam) / 537 ; 538 ; The following is OPTIONAL, 539 ; and MOST NOT occur more than once. 540 ; 541 (";" displayparam) 542 ; 543 ; The following is OPTIONAL, 544 ; and MAY occur more than once. 545 ; 546 (";" other-param) 547 ; 548 ) 550 Example: The following is an example of this property: 552 IMAGE;DISPLAY=BACKGROUND;FMTTYPE=image/png:htt 553 p://example.com/images/party.png 555 6. Property Parameters 557 6.1. DISPLAY Property Parameter 559 Parameter Name: DISPLAY 561 Purpose: To specify different ways in which an image for a calendar 562 or component can be displayed. 564 Format Definition: This property parameter is defined by the 565 following notation: 567 displayparam = "DISPLAY" "=" 568 ("BADGE" / ; A small "badge" image 569 "BACKGROUND" / ; Use as a background image 570 "OVERLAY" / ; Use as an overlay image 571 "BANNER" / ; Use as a "banner" across the top 572 x-name / ; Experimental type 573 iana-token) ; Other IANA registered type 574 ; 575 ; Default is BADGE 577 Description: This property parameter MAY be specified on "CALENDAR- 578 IMAGE" or "IMAGE" properties. In the absence of this parameter, 579 the value "BADGE" MUST be used for the default behavior. The 580 value determines how a client ought to present an image supplied 581 in iCalendar data to the user. 583 Servers and clients MUST treat x-name and iana-token values they 584 don't recognize the same way as they would the "NONE" value. 586 Example: 588 IMAGE;DISPLAY=BANNER;FMTTYPE=image/png:htt 589 p://example.com/images/weather-cloudy.png 591 7. Security Considerations 593 TODO:Perhaps discuss issues with image processing related buffer 594 overflows, accessing external URLs (privacy), etc. 596 8. IANA Considerations 598 8.1. Property Registrations 600 This documents defines the following new iCalendar properties to be 601 added to the registry defined in Section 8.2.3 of [RFC5545]: 603 +---------------------------+---------+----------------------+ 604 | Property | Status | Reference | 605 +---------------------------+---------+----------------------+ 606 | CALENDAR-NAME | Current | RFCXXXX, Section 4.1 | 607 | CALENDAR-DESCRIPTION | Current | RFCXXXX, Section 4.2 | 608 | CALENDAR-UID | Current | RFCXXXX, Section 4.3 | 609 | CALENDAR-URL | Current | RFCXXXX, Section 4.4 | 610 | CALENDAR-TZID | Current | RFCXXXX, Section 4.5 | 611 | CALENDAR-REFRESH-INTERVAL | Current | RFCXXXX, Section 4.6 | 612 | CALENDAR-COLOR | Current | RFCXXXX, Section 4.7 | 613 | CALENDAR-IMAGE | Current | RFCXXXX, Section 4.8 | 614 | IMAGE | Current | RFCXXXX, Section 5.1 | 615 +---------------------------+---------+----------------------+ 617 8.2. Paramater Registrations 619 This documents defines the following new iCalendar properties to be 620 added to the registry defined in Section 8.2.3 of [RFC5545]: 622 +--------------------+---------+----------------------+ 623 | Property Parameter | Status | Reference | 624 +--------------------+---------+----------------------+ 625 | DISPLAY | Current | RFCXXXX, Section 6.1 | 626 +--------------------+---------+----------------------+ 628 9. Acknowledgments 630 This specification came about via discussions at the Calendaring and 631 Scheduling Consortium. 633 10. References 635 10.1. Normative References 637 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 638 Requirement Levels", BCP 14, RFC 2119, March 1997. 640 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 641 Specifications: ABNF", STD 68, RFC 5234, January 2008. 643 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling 644 Core Object Specification (iCalendar)", RFC 5545, 645 September 2009. 647 10.2. Informative References 649 [RFC5546] Daboo, C., "iCalendar Transport-Independent 650 Interoperability Protocol (iTIP)", RFC 5546, 651 December 2009. 653 Author's Address 655 Cyrus Daboo 656 Apple Inc. 657 1 Infinite Loop 658 Cupertino, CA 95014 659 USA 661 Email: cyrus@daboo.name 662 URI: http://www.apple.com/