idnits 2.17.1 draft-daboo-icalendar-extensions-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 : ---------------------------------------------------------------------------- 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 (July 12, 2010) is 5036 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 (==), 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 July 12, 2010 5 Expires: January 13, 2011 7 New Properties for iCalendar 8 draft-daboo-icalendar-extensions-01 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 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). Note that other groups may also distribute 21 working documents as Internet-Drafts. The list of current Internet- 22 Drafts is at http://datatracker.ietf.org/drafts/current/. 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 This Internet-Draft will expire on January 13, 2011. 31 Copyright Notice 33 Copyright (c) 2010 IETF Trust and the persons identified as the 34 document authors. All rights reserved. 36 This document is subject to BCP 78 and the IETF Trust's Legal 37 Provisions Relating to IETF Documents 38 (http://trustee.ietf.org/license-info) in effect on the date of 39 publication of this document. Please review these documents 40 carefully, as they describe your rights and restrictions with respect 41 to this document. Code Components extracted from this document must 42 include Simplified BSD License text as described in Section 4.e of 43 the Trust Legal Provisions and are provided without warranty as 44 described in the Simplified BSD License. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 50 3. Modifications to Calendar Components . . . . . . . . . . . . . 3 51 4. Calendar Properties . . . . . . . . . . . . . . . . . . . . . 4 52 4.1. CALENDAR-NAME Property . . . . . . . . . . . . . . . . . . 5 53 4.2. CALENDAR-DESCRIPTION Property . . . . . . . . . . . . . . 6 54 4.3. CALENDAR-UID Property . . . . . . . . . . . . . . . . . . 7 55 4.4. CALENDAR-URL Property . . . . . . . . . . . . . . . . . . 7 56 4.5. CALENDAR-TZID Property . . . . . . . . . . . . . . . . . . 8 57 4.6. CALENDAR-REFRESH-INTERVAL Property . . . . . . . . . . . . 9 58 4.7. CALENDAR-COLOR Property . . . . . . . . . . . . . . . . . 10 59 4.8. CALENDAR-IMAGE Property . . . . . . . . . . . . . . . . . 10 60 5. Component Properties . . . . . . . . . . . . . . . . . . . . . 12 61 5.1. IMAGE Property . . . . . . . . . . . . . . . . . . . . . . 12 62 6. Property Parameters . . . . . . . . . . . . . . . . . . . . . 14 63 6.1. DISPLAY Property Parameter . . . . . . . . . . . . . . . . 14 64 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 65 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 66 8.1. Property Registrations . . . . . . . . . . . . . . . . . . 15 67 8.2. Parameter Registrations . . . . . . . . . . . . . . . . . 16 68 8.3. Display Types Registry . . . . . . . . . . . . . . . . . . 16 69 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 70 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 71 10.1. Normative References . . . . . . . . . . . . . . . . . . . 17 72 10.2. Informative References . . . . . . . . . . . . . . . . . . 17 73 Appendix A. Change History (To be removed by RFC Editor 74 before publication) . . . . . . . . . . . . . . . . . 17 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 17 77 1. Introduction 79 The iCalendar [RFC5545] data format is used to represent calendar 80 data and is used with iTIP [RFC5546] to handle scheduling operations 81 between calendar users. iCalendar is in widespread use, and in 82 accordance with provisions in that specification, extension elements 83 have been added by various vendors to the data format in order to 84 support and enhance capabilities. This specification collates a 85 number of these ad-hoc extensions and uses the new IANA registry 86 capability defined in [RFC5545] to register standard variants with 87 clearly defined definitions and semantics. In addition, some new 88 elements are introduced for features that vendors have been recently 89 requesting. 91 2. Conventions Used in This Document 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 95 "OPTIONAL" in this document are to be interpreted as described in 96 [RFC2119]. 98 The notation used in this memo is the ABNF notation of [RFC5234] as 99 used by iCalendar [RFC5545]. Any syntax elements shown below that 100 are not explicitly defined in this specification come from iCalendar 101 [RFC5545]. 103 3. Modifications to Calendar Components 105 The following changes to the syntax defined in iCalendar [RFC5545] 106 are made here. New elements are defined in subsequent sections. 108 calprops /= *( 109 ; 110 ; The following are OPTIONAL, 111 ; but MUST NOT occur more than once. 112 ; 113 caluid / calurl / caltzid / 114 calrefresh / calcolor / 115 ; 116 ; The following are OPTIONAL, 117 ; and MAY occur more than once. 118 ; 119 calname / caldescription / calimg 120 ; 121 ) 123 eventprop /= *( 124 ; 125 ; The following are OPTIONAL, 126 ; and MAY occur more than once. 127 ; 128 image 129 ; 130 ) 132 todoprop /= *( 133 ; 134 ; The following are OPTIONAL, 135 ; and MAY occur more than once. 136 ; 137 image 138 ; 139 ) 141 jourprop /= *( 142 ; 143 ; The following are OPTIONAL, 144 ; and MAY occur more than once. 145 ; 146 image 147 ; 148 ) 150 4. Calendar Properties 151 4.1. CALENDAR-NAME Property 153 Property Name: CALENDAR-NAME 155 Purpose: This property specifies the name of the calendar. 157 Value Type: TEXT 159 Property Parameters: IANA, non-standard, alternate text 160 representation, and language property parameters can be specified 161 on this property. 163 Conformance: This property can be specified multiple times in an 164 iCalendar object. However, each property MUST represent the name 165 of the calendar in a different language. 167 Description: This property is used to specify a name (a short, one- 168 line description) of the iCalendar object that can be used by 169 calendar user agents when presenting the calendar data to a user. 170 Whilst a calendar only has a single name, multiple language 171 variants can be specified by including this property multiple 172 times with different "LANGUAGE" parameter values on each. 174 Format Definition: This property is defined by the following 175 notation: 177 calname = "CALENDAR-NAME" calnameparam ":" text CRLF 179 calnameparam = *( 180 ; 181 ; The following are OPTIONAL, 182 ; but MUST NOT occur more than once. 183 ; 184 (";" altrepparam) / (";" languageparam) / 185 ; 186 ; The following is OPTIONAL, 187 ; and MAY occur more than once. 188 ; 189 (";" other-param) 190 ; 191 ) 193 Example: The following is an example of this property: 195 CALENDAR-NAME:Company Vacation Days 197 4.2. CALENDAR-DESCRIPTION Property 199 Property Name: CALENDAR-DESCRIPTION 201 Purpose: This property specifies the description of the calendar. 203 Value Type: TEXT 205 Property Parameters: IANA, non-standard, alternate text 206 representation, and language property parameters can be specified 207 on this property. 209 Conformance: This property can be specified multiple times in an 210 iCalendar object. However, each property MUST represent the 211 description of the calendar in a different language. 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. Whilst a calendar only has a single description, multiple 217 language variants can be specified by including this property 218 multiple times with different "LANGUAGE" parameter values on each. 220 Format Definition: This property is defined by the following 221 notation: 223 caldesc = "CALENDAR-DESCRIPTION" caldescparam ":" text 224 CRLF 226 caldescparam = *( 227 ; 228 ; The following are OPTIONAL, 229 ; but MUST NOT occur more than once. 230 ; 231 (";" altrepparam) / (";" languageparam) / 232 ; 233 ; The following is OPTIONAL, 234 ; and MAY occur more than once. 235 ; 236 (";" other-param) 237 ; 238 ) 240 Example: The following is an example of this property: 242 CALENDAR-DESCRIPTION:This calendar contains all the \ 243 official vacation days of our company.\nThese repre\ 244 sent paid time-off - make sure you have fun, we'll \ 245 be working you hard on the other days! 247 4.3. CALENDAR-UID Property 249 Property Name: CALENDAR-UID 251 Purpose: This property specifies the persistent, globally unique 252 identifier for the calendar. 254 Value Type: TEXT 256 Property Parameters: IANA and non-standard property parameters can 257 be specified on this property. 259 Conformance: This property can be specified once in an iCalendar 260 object. 262 Description: The value of this property MUST be a globally unique 263 identifier. The generator of the property MUST guarantee that the 264 value is unique. This can be done following the recommendations 265 in Section 3.8.4.7 of [RFC5545]. Implementations MUST be able to 266 receive and persist values of at least 255 octets for this 267 property, but they MUST NOT truncate values in the middle of a 268 UTF-8 multi-octet sequence. 270 Format Definition: This property is defined by the following 271 notation: 273 caluid = "CALENDAR-UID" caluidparam ":" text CRLF 275 caluidparam = *(";" other-param) 277 Example: The following is an example of this property: 279 CALENDAR-UID:19960401T080045Z-4000F192713-0052@example.com 281 4.4. CALENDAR-URL Property 283 Property Name: CALENDAR-URL 285 Purpose: This property specifies a URL from where the calendar data 286 was retrieved or where it can be refreshed. 288 Value Type: URI 289 Property Parameters: IANA and non-standard property parameters can 290 be specified on this property. 292 Conformance: This property can be specified once in an iCalendar 293 object. 295 Description: This property specifies a URL identifying the source of 296 the calendar data and a location from where updates can be 297 retrieved. 299 Format Definition: This property is defined by the following 300 notation: 302 calurl = "CALENDAR-URL" calurlparam ":" url CRLF 304 calurlparam = *(";" other-param) 306 Example: The following is an example of this property: 308 CALENDAR-URL:http://calendars.example.com/holidays/canada.ics 310 4.5. CALENDAR-TZID Property 312 Property Name: CALENDAR-TZID 314 Purpose: This property specifies the default time zone identifier 315 for the calendar. 317 Value Type: TEXT 319 Property Parameters: IANA and non-standard property parameters can 320 be specified on this property. 322 Conformance: This property can be specified once in an iCalendar 323 object. 325 Description: This property specifies a time zone identifier that 326 represents the default timezone for which floating time or all-day 327 events in the iCalendar object can be assumed to be relative to. 328 It can also be used to choose an initial time zone for use when 329 creating new components in the iCalendar object. A "VTIMEZONE" 330 component having a "TZID" property matching the value specified in 331 this property MUST be present in the iCalendar object. 333 Format Definition: This property is defined by the following 334 notation: 336 caltzid = "CALENDAR-TZID" caltzidparam ":" [tzidprefix] 337 text CRLF 339 caltzidparam = *(";" other-param) 341 Example: The following is an example of this property: 343 CALENDAR-TZID:America/New_York 345 4.6. CALENDAR-REFRESH-INTERVAL Property 347 Property Name: CALENDAR-REFRESH-INTERVAL 349 Purpose: This property specifies a suggested interval for polling 350 for changes of the calendar data from the original source of that 351 data. 353 Value Type: DURATION 355 Property Parameters: IANA and non-standard property parameters can 356 be specified on this property. 358 Conformance: This property can be specified once in an iCalendar 359 object. 361 Description: This property specifies a positive duration that gives 362 a suggested polling interval for checking for updates to the 363 calendar data. The value of this property SHOULD be used by 364 calendar user agents as the polling interval for calendar data 365 updates. 367 Format Definition: This property is defined by the following 368 notation: 370 calrefesh = "CALENDAR-REFRESH-INTERVAL" calrefreshparam 371 ":" dur-value CRLF 372 ;consisting of a positive duration of time. 374 calrefeshparam = *(";" other-param) 376 Example: The following is an example of this property: 378 CALENDAR-REFRESH-INTERVAL:P1W 380 4.7. CALENDAR-COLOR Property 382 Property Name: CALENDAR-COLOR 384 Purpose: This property specifies a color used for displaying the 385 calendar data. 387 Value Type: INTEGER. The value MUST be three SEMICOLON-separated 388 INTEGER values. 390 Property Parameters: IANA and non-standard property parameters can 391 be specified on this property. 393 Conformance: This property can be specified once in an iCalendar 394 object. 396 Description: This property specifies a color that client MAY use 397 when presenting the calendar data to a user. Typically this would 398 appear as the "background" color of events or tasks. The value 399 MUST be an RGB value with integer value components in the range 400 0..255 402 Format Definition: This property is defined by the following 403 notation: 405 calcolor = "CALENDAR-COLOR" calcolorparam ":" 406 calcolorvalue CRLF 408 calcolorparam = *(";" other-param) 410 calcolorvalue = integer ";" integer ";" integer 411 ; Red, green, and blue values in the range 412 ; 0 - 255. 414 Example: The following is an example of this property: 416 CALENDAR-COLOR:255;0;255 418 4.8. CALENDAR-IMAGE Property 420 Property Name: CALENDAR-IMAGE 422 Purpose: This property specifies an image associated with the 423 calendar. 425 Value Type: The default value type for this property is URI. The 426 value type can also be set to BINARY to indicate inline binary 427 encoded content information. The value MUST refer to or be data 428 with a media type of "image". 430 Property Parameters: IANA, non-standard, display, inline encoding, 431 and value data type property parameters can be specified on this 432 property. The format type parameter can be specified on this 433 property and is RECOMMENDED for inline binary encoded content 434 information. 436 Conformance: This property can be specified multiple times in an 437 iCalendar object. 439 Description: This property specifies an image for an iCalendar 440 object via a uri or directly with inline data that can be used by 441 calendar user agents when presenting the calendar data to a user. 442 Multiple properties MAY be used to specify alternative sets of 443 images with, for example, varying media subtypes, resolutions or 444 sizes. When multiple properties are present, calendar user agents 445 SHOULD display only one of them, picking one that provides the 446 most appropriate image quality, or display none. The "DISPLAY" 447 parameter is used to indicate the intended display mode for the 448 image. 450 Format Definition: This property is defined by the following 451 notation: 453 calimg = "CALENDAR-IMAGE" calimgparam ( ":" uri ) / 454 ( 455 ";" "ENCODING" "=" "BASE64" 456 ";" "VALUE" "=" "BINARY" 457 ":" binary 458 ) 459 CRLF 461 calimgparam = *( 462 ; 463 ; The following is OPTIONAL for a URI value, 464 ; RECOMMENDED for a BINARY value, 465 ; and MUST NOT occur more than once. 466 ; 467 (";" fmttypeparam) / 468 ; 469 ; The following is OPTIONAL, 470 ; and MOST NOT occur more than once. 471 ; 472 (";" displayparam) 473 ; 474 ; The following is OPTIONAL, 475 ; and MAY occur more than once. 476 ; 477 (";" other-param) 478 ; 479 ) 481 Example: The following is an example of this property: 483 CALENDAR-IMAGE;DISPLAY=BADGE;FMTTYPE=image/png:http://ex 484 ample.com/images/holiday.png 486 5. Component Properties 488 5.1. IMAGE Property 490 Property Name: IMAGE 492 Purpose: This property specifies an image associated with a calendar 493 component. 495 Value Type: The default value type for this property is URI. The 496 value type can also be set to BINARY to indicate inline binary 497 encoded content information. The value MUST refer to or be data 498 with a media type of "image". 500 Property Parameters: IANA, non-standard, display, inline encoding, 501 and value data type property parameters can be specified on this 502 property. The format type parameter can be specified on this 503 property and is RECOMMENDED for inline binary encoded content 504 information. 506 Conformance: This property can be specified multiple times in a 507 "VEVENT", "VTODO", or "VJOURNAL" calendar component. 509 Description: This property specifies an image for a calendar 510 component via a uri or directly with inline data that can be used 511 by calendar user agents when presenting the calendar data to a 512 user. Multiple properties MAY be used to specify alternative sets 513 of images with, for example, varying media subtypes, resolutions 514 or sizes. When multiple properties are present, calendar user 515 agents SHOULD display only one of them, picking one that provides 516 the most appropriate image quality, or display none. The 517 "DISPLAY" parameter is used to indicate the intended display mode 518 for the image. 520 Format Definition: This property is defined by the following 521 notation: 523 image = "IMAGE" imageparam ( ":" uri ) / 524 ( 525 ";" "ENCODING" "=" "BASE64" 526 ";" "VALUE" "=" "BINARY" 527 ":" binary 528 ) 529 CRLF 531 imageparam = *( 532 ; 533 ; The following is OPTIONAL for a URI value, 534 ; RECOMMENDED for a BINARY value, 535 ; and MUST NOT occur more than once. 536 ; 537 (";" fmttypeparam) / 538 ; 539 ; The following is OPTIONAL, 540 ; and MOST NOT occur more than once. 541 ; 542 (";" displayparam) 543 ; 544 ; The following is OPTIONAL, 545 ; and MAY occur more than once. 546 ; 547 (";" other-param) 548 ; 549 ) 551 Example: The following is an example of this property: 553 IMAGE;DISPLAY=BACKGROUND;FMTTYPE=image/png:htt 554 p://example.com/images/party.png 556 6. Property Parameters 558 6.1. DISPLAY Property Parameter 560 Parameter Name: DISPLAY 562 Purpose: To specify different ways in which an image for a calendar 563 or component can be displayed. 565 Format Definition: This property parameter is defined by the 566 following notation: 568 displayparam = "DISPLAY" "=" 569 ("BADGE" / ; A small "badge" image 570 "BACKGROUND" / ; Use as a background image 571 "OVERLAY" / ; Use as an overlay image 572 "BANNER" / ; Use as a "banner" across the top 573 x-name / ; Experimental type 574 iana-token) ; Other IANA registered type 575 ; 576 ; Default is BADGE 578 Description: This property parameter MAY be specified on "CALENDAR- 579 IMAGE" or "IMAGE" properties. In the absence of this parameter, 580 the value "BADGE" MUST be used for the default behavior. The 581 value determines how a client ought to present an image supplied 582 in iCalendar data to the user. 584 Values for this parameter are registered with IANA as per 585 Section 8.3. New values can be added to this registry following 586 the procedure outlined in Section 8.2.1 of [RFC5545]. 588 Servers and clients MUST handle x-name and iana-token values they 589 don't recognize by not displaying any image at all. 591 Example: 593 IMAGE;DISPLAY=BANNER;FMTTYPE=image/png:htt 594 p://example.com/images/weather-cloudy.png 596 7. Security Considerations 598 TODO:Perhaps discuss issues with image processing related buffer 599 overflows, accessing external URLs (privacy), etc. 601 8. IANA Considerations 603 8.1. Property Registrations 605 This document defines the following new iCalendar properties to be 606 added to the registry defined in Section 8.2.3 of [RFC5545]: 608 +---------------------------+---------+----------------------+ 609 | Property | Status | Reference | 610 +---------------------------+---------+----------------------+ 611 | CALENDAR-NAME | Current | RFCXXXX, Section 4.1 | 612 | CALENDAR-DESCRIPTION | Current | RFCXXXX, Section 4.2 | 613 | CALENDAR-UID | Current | RFCXXXX, Section 4.3 | 614 | CALENDAR-URL | Current | RFCXXXX, Section 4.4 | 615 | CALENDAR-TZID | Current | RFCXXXX, Section 4.5 | 616 | CALENDAR-REFRESH-INTERVAL | Current | RFCXXXX, Section 4.6 | 617 | CALENDAR-COLOR | Current | RFCXXXX, Section 4.7 | 618 | CALENDAR-IMAGE | Current | RFCXXXX, Section 4.8 | 619 | IMAGE | Current | RFCXXXX, Section 5.1 | 620 +---------------------------+---------+----------------------+ 622 8.2. Parameter Registrations 624 This document defines the following new iCalendar property parameters 625 to be added to the registry defined in Section 8.2.4 of [RFC5545]: 627 +--------------------+---------+----------------------+ 628 | Property Parameter | Status | Reference | 629 +--------------------+---------+----------------------+ 630 | DISPLAY | Current | RFCXXXX, Section 6.1 | 631 +--------------------+---------+----------------------+ 633 8.3. Display Types Registry 635 This document defines the following new iCalendar value registry as 636 per Section 8.2.6 of [RFC5545]: 638 +--------------+---------+----------------------+ 639 | Display Type | Status | Reference | 640 +--------------+---------+----------------------+ 641 | BADGE | Current | RFCXXXX, Section 6.1 | 642 | BACKGROUND | Current | RFCXXXX, Section 6.1 | 643 | OVERLAY | Current | RFCXXXX, Section 6.1 | 644 | BANNER | Current | RFCXXXX, Section 6.1 | 645 +--------------+---------+----------------------+ 647 9. Acknowledgments 649 This specification came about via discussions at the Calendaring and 650 Scheduling Consortium. 652 10. References 653 10.1. Normative References 655 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 656 Requirement Levels", BCP 14, RFC 2119, March 1997. 658 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 659 Specifications: ABNF", STD 68, RFC 5234, January 2008. 661 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling 662 Core Object Specification (iCalendar)", RFC 5545, 663 September 2009. 665 10.2. Informative References 667 [RFC5546] Daboo, C., "iCalendar Transport-Independent 668 Interoperability Protocol (iTIP)", RFC 5546, 669 December 2009. 671 Appendix A. Change History (To be removed by RFC Editor before 672 publication) 674 Changes in -01: 676 1. Fixed DISPLAY parameter handling of x- and iana tokens to state 677 that clients ignore the image if the token is not recognized. 679 2. Allow language variants for CALENDAR-NAME and CALENDAR- 680 DESCRIPTION. 682 3. Added registry for DISPLAY values. 684 Author's Address 686 Cyrus Daboo 687 Apple Inc. 688 1 Infinite Loop 689 Cupertino, CA 95014 690 USA 692 Email: cyrus@daboo.name 693 URI: http://www.apple.com/