Network Working Group C. Daboo
Internet-Draft Apple Inc.
Intended status: Standards Track October 18, 2012
Expires: April 19, 2013

New Properties for iCalendar
draft-daboo-icalendar-extensions-01

Abstract

This document defines a set of new properties for 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 April 19, 2013.

Copyright Notice

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

The iCalendar [RFC5545] data format is used to represent calendar data and is used with iTIP [RFC5546] to handle scheduling operations between calendar users. iCalendar is in widespread use, and in accordance with provisions in that specification, extension elements have been added by various vendors to the data format in order to support and enhance capabilities. This specification collates a number of these ad-hoc extensions and uses the new IANA registry capability defined in [RFC5545] to register standard variants with clearly defined definitions and semantics. In addition, some new elements are introduced for features that vendors have been recently requesting.

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

3. Modifications to Calendar Components


       calprops /= *(
                    ;
                    ; The following are OPTIONAL,
                    ; but MUST NOT occur more than once.
                    ;
                    caluid / calurl / caltzid /
                    calrefresh / calcolor /
                    ;
                    ; The following are OPTIONAL,
                    ; and MAY occur more than once.
                    ;
                    calname / caldescription / calimg
                    ;
                    )

       eventprop /= *(
                     ;
                     ; The following are OPTIONAL,
                     ; and MAY occur more than once.
                     ;
                     image
                     ;
                     )

       todoprop /= *(
                    ;
                    ; The following are OPTIONAL,
                    ; and MAY occur more than once.
                    ;
                    image
                    ;
                    )

       jourprop /= *(
                    ;
                    ; The following are OPTIONAL,
                    ; and MAY occur more than once.
                    ;
                    image
                    ;
                    )

The following changes to the syntax defined in iCalendar [RFC5545] are made here. New elements are defined in subsequent sections.

4. Calendar Properties

4.1. CALENDAR-NAME Property

       calname       = "CALENDAR-NAME" calnameparam ":" text CRLF

       calnameparam  = *(
                        ;
                        ; The following are OPTIONAL,
                        ; but MUST NOT occur more than once.
                        ;
                        (";" altrepparam) / (";" languageparam) /
                        ;
                        ; The following is OPTIONAL,
                        ; and MAY occur more than once.
                        ;
                        (";" other-param)
                        ;
                        )
                            
       CALENDAR-NAME:Company Vacation Days

Property Name:
CALENDAR-NAME
Purpose:
This property specifies the name of the calendar.
Value Type:
TEXT
Property Parameters:
IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:
This property can be specified multiple times in an iCalendar object. However, each property MUST represent the name of the calendar in a different language.
Description:
This property is used to specify a name (a short, one-line description) of the iCalendar object that can be used by calendar user agents when presenting the calendar data to a user. Whilst a calendar only has a single name, multiple language variants can be specified by including this property multiple times with different "LANGUAGE" parameter values on each.
Format Definition:
This property is defined by the following notation:
Example:
The following is an example of this property:

4.2. CALENDAR-DESCRIPTION Property

       caldesc       = "CALENDAR-DESCRIPTION" caldescparam ":" text
                       CRLF

       caldescparam  = *(
                        ;
                        ; The following are OPTIONAL,
                        ; but MUST NOT occur more than once.
                        ;
                        (";" altrepparam) / (";" languageparam) /
                        ;
                        ; The following is OPTIONAL,
                        ; and MAY occur more than once.
                        ;
                        (";" other-param)
                        ;
                        )
                            
       CALENDAR-DESCRIPTION:This calendar contains all the \
        official vacation days of our company.\nThese repre\
        sent paid time-off - make sure you have fun, we'll \
        be working you hard on the other days!

Property Name:
CALENDAR-DESCRIPTION
Purpose:
This property specifies the description of the calendar.
Value Type:
TEXT
Property Parameters:
IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:
This property can be specified multiple times in an iCalendar object. However, each property MUST represent the description of the calendar in a different language.
Description:
This property is used to specify a lengthy textual description of the iCalendar object that can be used by calendar user agents when describing the nature of the calendar data to a user. Whilst a calendar only has a single description, multiple language variants can be specified by including this property multiple times with different "LANGUAGE" parameter values on each.
Format Definition:
This property is defined by the following notation:
Example:
The following is an example of this property:

4.3. CALENDAR-UID Property

       caluid       = "CALENDAR-UID" caluidparam ":" text CRLF

       caluidparam  = *(";" other-param)
                            
       CALENDAR-UID:19960401T080045Z-4000F192713-0052@example.com

Property Name:
CALENDAR-UID
Purpose:
This property specifies the persistent, globally unique identifier for the calendar.
Value Type:
TEXT
Property Parameters:
IANA and non-standard property parameters can be specified on this property.
Conformance:
This property can be specified once in an iCalendar object.
Description:
The value of this property MUST be a globally unique identifier. The generator of the property MUST guarantee that the value is unique. This can be done following the recommendations in Section 3.8.4.7 of [RFC5545]. Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.
Format Definition:
This property is defined by the following notation:
Example:
The following is an example of this property:

4.4. CALENDAR-URL Property

       calurl       = "CALENDAR-URL" calurlparam ":" url CRLF

       calurlparam  = *(";" other-param)
                            
       CALENDAR-URL:http://calendars.example.com/holidays/canada.ics

Property Name:
CALENDAR-URL
Purpose:
This property specifies a URL from where the calendar data was retrieved or where it can be refreshed.
Value Type:
URI
Property Parameters:
IANA and non-standard property parameters can be specified on this property.
Conformance:
This property can be specified once in an iCalendar object.
Description:
This property specifies a URL identifying the source of the calendar data and a location from where updates can be retrieved.
Format Definition:
This property is defined by the following notation:
Example:
The following is an example of this property:

4.5. CALENDAR-TZID Property

       caltzid       = "CALENDAR-TZID" caltzidparam ":" [tzidprefix]
                       text CRLF

       caltzidparam  = *(";" other-param)
                            
       CALENDAR-TZID:America/New_York

Property Name:
CALENDAR-TZID
Purpose:
This property specifies the default time zone identifier for the calendar.
Value Type:
TEXT
Property Parameters:
IANA and non-standard property parameters can be specified on this property.
Conformance:
This property can be specified once in an iCalendar object.
Description:
This property specifies a time zone identifier that represents the default timezone for which floating time or all-day events in the iCalendar object can be assumed to be relative to. It can also be used to choose an initial time zone for use when creating new components in the iCalendar object. A "VTIMEZONE" component having a "TZID" property matching the value specified in this property MUST be present in the iCalendar object.
Format Definition:
This property is defined by the following notation:
Example:
The following is an example of this property:

4.6. CALENDAR-REFRESH-INTERVAL Property

       calrefesh      = "CALENDAR-REFRESH-INTERVAL" calrefreshparam
                        ":" dur-value CRLF
                        ;consisting of a positive duration of time.

       calrefeshparam = *(";" other-param)
                            
       CALENDAR-REFRESH-INTERVAL:P1W

Property Name:
CALENDAR-REFRESH-INTERVAL
Purpose:
This property specifies a suggested interval for polling for changes of the calendar data from the original source of that data.
Value Type:
DURATION
Property Parameters:
IANA and non-standard property parameters can be specified on this property.
Conformance:
This property can be specified once in an iCalendar object.
Description:
This property specifies a positive duration that gives a suggested polling interval for checking for updates to the calendar data. The value of this property SHOULD be used by calendar user agents as the polling interval for calendar data updates.
Format Definition:
This property is defined by the following notation:
Example:
The following is an example of this property:

4.7. CALENDAR-COLOR Property

       calcolor       = "CALENDAR-COLOR" calcolorparam ":"
                        calcolorvalue CRLF

       calcolorparam  = *(";" other-param)

       calcolorvalue  = integer ";" integer ";" integer
                        ; Red, green, and blue values in the range
                        ; 0 - 255.
                            
       CALENDAR-COLOR:255;0;255

Property Name:
CALENDAR-COLOR
Purpose:
This property specifies a color used for displaying the calendar data.
Value Type:
INTEGER. The value MUST be three SEMICOLON-separated INTEGER values.
Property Parameters:
IANA and non-standard property parameters can be specified on this property.
Conformance:
This property can be specified once in an iCalendar object.
Description:
This property specifies a color that client MAY use when presenting the calendar data to a user. Typically this would appear as the "background" color of events or tasks. The value MUST be an RGB value with integer value components in the range 0..255
Format Definition:
This property is defined by the following notation:
Example:
The following is an example of this property:

4.8. CALENDAR-IMAGE Property

       calimg     = "CALENDAR-IMAGE" calimgparam ( ":" uri ) /
                    (
                      ";" "ENCODING" "=" "BASE64"
                      ";" "VALUE" "=" "BINARY"
                      ":" binary
                    )
                    CRLF

       calimgparam = *(
                      ;
                      ; The following is OPTIONAL for a URI value,
                      ; RECOMMENDED for a BINARY value,
                      ; and MUST NOT occur more than once.
                      ;
                      (";" fmttypeparam) /
                      ;
                      ; The following is OPTIONAL,
                      ; and MOST NOT occur more than once.
                      ;
                      (";" displayparam)
                      ;
                      ; The following is OPTIONAL,
                      ; and MAY occur more than once.
                      ;
                      (";" other-param)
                      ;
                      )
                            
       CALENDAR-IMAGE;DISPLAY=BADGE;FMTTYPE=image/png:http://ex
        ample.com/images/holiday.png

Property Name:
CALENDAR-IMAGE
Purpose:
This property specifies an image associated with the calendar.
Value Type:
The default value type for this property is URI. The value type can also be set to BINARY to indicate inline binary encoded content information. The value MUST refer to or be data with a media type of "image".
Property Parameters:
IANA, non-standard, display, inline encoding, and value data type property parameters can be specified on this property. The format type parameter can be specified on this property and is RECOMMENDED for inline binary encoded content information.
Conformance:
This property can be specified multiple times in an iCalendar object.
Description:
This property specifies an image for an iCalendar object via a uri or directly with inline data that can be used by calendar user agents when presenting the calendar data to a user. Multiple properties MAY be used to specify alternative sets of images with, for example, varying media subtypes, resolutions or sizes. When multiple properties are present, calendar user agents SHOULD display only one of them, picking one that provides the most appropriate image quality, or display none. The "DISPLAY" parameter is used to indicate the intended display mode for the image.
Format Definition:
This property is defined by the following notation:
Example:
The following is an example of this property:

5. Component Properties

5.1. IMAGE Property

       image      = "IMAGE" imageparam ( ":" uri ) /
                    (
                      ";" "ENCODING" "=" "BASE64"
                      ";" "VALUE" "=" "BINARY"
                      ":" binary
                    )
                    CRLF

       imageparam = *(
                     ;
                     ; The following is OPTIONAL for a URI value,
                     ; RECOMMENDED for a BINARY value,
                     ; and MUST NOT occur more than once.
                     ;
                     (";" fmttypeparam) /
                     ;
                     ; The following is OPTIONAL,
                     ; and MOST NOT occur more than once.
                     ;
                     (";" displayparam)
                     ;
                     ; The following is OPTIONAL,
                     ; and MAY occur more than once.
                     ;
                     (";" other-param)
                     ;
                     )
                            
       IMAGE;DISPLAY=BACKGROUND;FMTTYPE=image/png:htt
        p://example.com/images/party.png

Property Name:
IMAGE
Purpose:
This property specifies an image associated with a calendar component.
Value Type:
The default value type for this property is URI. The value type can also be set to BINARY to indicate inline binary encoded content information. The value MUST refer to or be data with a media type of "image".
Property Parameters:
IANA, non-standard, display, inline encoding, and value data type property parameters can be specified on this property. The format type parameter can be specified on this property and is RECOMMENDED for inline binary encoded content information.
Conformance:
This property can be specified multiple times in a "VEVENT", "VTODO", or "VJOURNAL" calendar component.
Description:
This property specifies an image for a calendar component via a uri or directly with inline data that can be used by calendar user agents when presenting the calendar data to a user. Multiple properties MAY be used to specify alternative sets of images with, for example, varying media subtypes, resolutions or sizes. When multiple properties are present, calendar user agents SHOULD display only one of them, picking one that provides the most appropriate image quality, or display none. The "DISPLAY" parameter is used to indicate the intended display mode for the image.
Format Definition:
This property is defined by the following notation:
Example:
The following is an example of this property:

6. Property Parameters

6.1. DISPLAY Property Parameter

   displayparam = "DISPLAY" "="
                  ("BADGE" /       ; A small "badge" image
                   "BACKGROUND" /  ; Use as a background image
                   "OVERLAY" /     ; Use as an overlay image
                   "BANNER" /      ; Use as a "banner" across the top
                   x-name /        ; Experimental type
                   iana-token)     ; Other IANA registered type
                                   ;
                                   ; Default is BADGE
                    
       IMAGE;DISPLAY=BANNER;FMTTYPE=image/png:htt
        p://example.com/images/weather-cloudy.png

Parameter Name:
DISPLAY
Purpose:
To specify different ways in which an image for a calendar or component can be displayed.
Format Definition:
This property parameter is defined by the following notation:
Description:
This property parameter MAY be specified on "CALENDAR-IMAGE" or "IMAGE" properties. In the absence of this parameter, the value "BADGE" MUST be used for the default behavior. The value determines how a client ought to present an image supplied in iCalendar data to the user.
Values for this parameter are registered with IANA as per Section 8.3. New values can be added to this registry following the procedure outlined in Section 8.2.1 of [RFC5545].
Servers and clients MUST handle x-name and iana-token values they don't recognize by not displaying any image at all.
Example:

7. Security Considerations

TODO:Perhaps discuss issues with image processing related buffer overflows, accessing external URLs (privacy), etc.

8. IANA Considerations

8.1. Property Registrations

This document defines the following new iCalendar properties to be added to the registry defined in Section 8.2.3 of [RFC5545]:

Property Status Reference
CALENDAR-NAME Current RFCXXXX, Section 4.1
CALENDAR-DESCRIPTION Current RFCXXXX, Section 4.2
CALENDAR-UID Current RFCXXXX, Section 4.3
CALENDAR-URL Current RFCXXXX, Section 4.4
CALENDAR-TZID Current RFCXXXX, Section 4.5
CALENDAR-REFRESH-INTERVAL Current RFCXXXX, Section 4.6
CALENDAR-COLOR Current RFCXXXX, Section 4.7
CALENDAR-IMAGE Current RFCXXXX, Section 4.8
IMAGE Current RFCXXXX, Section 5.1

8.2. Parameter Registrations

This document defines the following new iCalendar property parameters to be added to the registry defined in Section 8.2.4 of [RFC5545]:

Property Parameter Status Reference
DISPLAY Current RFCXXXX, Section 6.1

8.3. Display Types Registry

This document defines the following new iCalendar value registry as per Section 8.2.6 of [RFC5545]:

Display Type Status Reference
BADGE Current RFCXXXX, Section 6.1
BACKGROUND Current RFCXXXX, Section 6.1
OVERLAY Current RFCXXXX, Section 6.1
BANNER Current RFCXXXX, Section 6.1

9. Acknowledgments

This specification came about via discussions at the Calendaring and Scheduling Consortium.

10. References

10.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, September 2009.

10.2. Informative References

[RFC5546] Daboo, C., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, December 2009.

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

Changes in -01:

  1. Fixed DISPLAY parameter handling of x- and iana tokens to state that clients ignore the image if the token is not recognized.
  2. Allow language variants for CALENDAR-NAME and CALENDAR-DESCRIPTION.
  3. Added registry for DISPLAY values.

Author's Address

Cyrus Daboo Apple Inc. 1 Infinite Loop Cupertino , CA 95014 USA EMail: cyrus@daboo.name URI: http://www.apple.com/