New Properties for iCalendar
draft-ietf-calext-extensions-03

Abstract

This document defines a set of new properties for iCalendar data as well as extending the use of some existing properties to the entire iCalendar object.

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 December 6, 2016.

Copyright Notice

Copyright (c) 2016 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
• 2. Conventions Used in This Document
• 3. Backwards Compatible Extension Properties
• 4. Modifications to Calendar Components
• 5. Properties
• 5.1. NAME Property
• 5.2. DESCRIPTION Property
• 5.3. UID Property
• 5.4. LAST-MODIFIED Property
• 5.5. URL Property
• 5.6. CATEGORIES Property
• 5.7. REFRESH-INTERVAL Property
• 5.8. SOURCE Property
• 5.9. COLOR Property
• 5.10. IMAGE Property
• 5.11. CONFERENCE Property
• 6. Property Parameters
• 6.1. DISPLAY Property Parameter
• 6.2. EMAIL Property Parameter
• 6.3. FEATURE Property Parameter
• 6.4. LABEL Property Parameter
• 7. Security Considerations
• 8. IANA Considerations
• 8.1. Property Registrations
• 8.2. Parameter Registrations
• 8.3. Display Types Registry
• 8.4. Feature Types Registry
• 9. Acknowledgments
• 10. References
• 10.1. Normative References
• 10.2. Informative References
• Appendix A. Change History (To be removed by RFC Editor before publication)
• Author's Address

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 collects 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 recently been 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. Backwards Compatible Extension Properties

iCalendar defines properties which can have different value types indicated by a "VALUE" parameter. The definition of a property specifies a "default" value type that is assumed to be used when no "VALUE" parameter is present. However, this poses a problem to iCalendar parser/generator software that does not know about the default values for new properties. For example, if a new property "FOO" were defined with a default value type of URI, and a URI value with a comma was used, an iCalendar generator not aware of this fact would likely treat the property value as "TEXT" and apply backslash escaping to the comma in the value, effectively making it an invalid URI value.

To avoid this problem, this specification recommends that all properties not defined in [RFC5545], always include a "VALUE" parameter, if the type is other than "TEXT". i.e., in the example above, the "FOO" property would have a "VALUE=URI" parameter. This allows iCalendar parser/generator software to track the correct types of unknown properties.

New properties defined in this specification use the term "no default" in the "Value Type" definition to indicate that the "VALUE" parameter has to be included.

4. Modifications to Calendar Components

calprops =/ *(
             ;
             ; The following are OPTIONAL,
             ; but MUST NOT occur more than once.
             ;
             uid / last-mod / url /
             refresh / source / color
             ;
             ; The following are OPTIONAL,
             ; and MAY occur more than once.
             ;
             name / description / categories /
             image
             ;
             )

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

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

jourprop =/ *(
             ;
             ; The following are OPTIONAL,
             ; but MUST NOT occur more than once.
             ;
             color /
             ;
             ; 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.

5. Properties

5.1. NAME Property

name       = "NAME" nameparam ":" text CRLF

nameparam  = *(
              ;
              ; 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)
              ;
              )

NAME:Company Vacation Days

Property Name:

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 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:

5.2. DESCRIPTION Property

This specification modifies the definition of the "DESCRIPTION" property to allow it to be defined on an iCalendar object. The following additions are made to the definition of this property.

Purpose:

This property specifies the description of the calendar.

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.

5.3. UID Property

This specification modifies the definition of the "UID" property to allow it to be defined on an iCalendar object. The following additions are made to the definition of this property.

Purpose:

This property specifies the persistent, globally unique identifier for the iCalendar object. This can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the "LAST-MODIFIED" property also specified on the "VCALENDAR" object, to identify the most recent version of a calendar.

Conformance:

This property can be specified once in an iCalendar object.

5.4. LAST-MODIFIED Property

This specification modifies the definition of the "LAST-MODIFIED" property to allow it to be defined on an iCalendar object. The following additions are made to the definition of this property.

Purpose:

This property specifies the date and time that the information associated with the calendar was last revised.

Conformance:

This property can be specified once in an iCalendar object.

5.5. URL Property

This specification modifies the definition of the "URL" property to allow it to be defined on an iCalendar object. The following additions are made to the definition of this property.

Purpose:

This property may be used to convey a location where a more dynamic rendition of the calendar information can be found.

Conformance:

This property can be specified once in an iCalendar object.

5.6. CATEGORIES Property

This specification modifies the definition of the "CATEGORIES" property to allow it to be defined on an iCalendar object. The following additions are made to the definition of this property.

Purpose:

This property defines the categories for an entire calendar.

Conformance:

This property can be specified multiple times in an iCalendar object.

Description:

When multiple properties are present, the set of categories that apply to the iCalendar object are the union of all the categories listed in each property value.

5.7. REFRESH-INTERVAL Property

refresh      = "REFRESH-INTERVAL" refreshparam
                 ":" dur-value CRLF
                 ;consisting of a positive duration of time.

refreshparam = *(
                ;
                ; The following is REQUIRED,
                ; but MUST NOT occur more than once.
                ;
                (";" "VALUE" "=" "DURATION") /
                ;
                ; The following is OPTIONAL,
                ; and MAY occur more than once.
                ;
                (";" other-param)
                ;
                )

REFRESH-INTERVAL;VALUE=DURATION:P1W

Property Name:

REFRESH-INTERVAL

Purpose:

This property specifies a suggested minimum interval for polling for changes of the calendar data from the original source of that data.

Value Type:

DURATION - no default

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 minimum polling interval for checking for updates to the calendar data. The value of this property SHOULD be used by calendar user agents to limit the polling interval for calendar data updates to the minimum interval specified.

Format Definition:

This property is defined by the following notation:

Example:

The following is an example of this property:

5.8. SOURCE Property

source       = "SOURCE" sourceparam ":" uri CRLF

sourceparam = *(";" other-param)

SOURCE;VALUE=URI:https://example.com/holidays.ics

Property Name:

SOURCE

Purpose:

This property identified a URI where calendar data can be refreshed from.

Value Type:

URI - no default

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 identifies a location where a client can retrieve updated data for the calendar. Clients SHOULD honor any specified "REFRESH-INTERVAL" value when periodically retrieving data. Note that this property differs from the "URL" property in that "URL" is meant to provide an alternative representation of the calendar data, rather than the original location of the data.

Format Definition:

This property is defined by the following notation:

Example:

The following is an example of this property:

5.9. COLOR Property

color          = "COLOR" colorparam ":" text CRLF
                  ; Value is CSS3 color name

colorparam     = *(";" other-param)

COLOR:turquoise

Property Name:

COLOR

Purpose:

This property specifies a color used for displaying the calendar, event, todo, or journal data.

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, or "VEVENT", "VTODO", or "VJOURNAL" calendar components.

Description:

This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically this would appear as the "background" color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of [W3C.REC-css3-color-20110607].

Format Definition:

This property is defined by the following notation:

Example:

The following is an example of this property:

5.10. IMAGE Property

image      = "IMAGE" imageparam
             (
               (
                 ";" "VALUE" "=" "URI"
                 ":" 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 are OPTIONAL,
              ; and MUST NOT occur more than once.
              ;
              (";" altrepparam) / (";" displayparam) /
              ;
              ; The following is OPTIONAL,
              ; and MAY occur more than once.
              ;
              (";" other-param)
              ;
              )

IMAGE;VALUE=URI;DISPLAY=BADGE;FMTTYPE=image/png:h
 ttp://example.com/images/party.png

Property Name:

IMAGE

Purpose:

This property specifies an image associated with the calendar or a calendar component.

Value Type:

URI or BINARY - no default. 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, or "VEVENT", "VTODO", or "VJOURNAL" calendar components.

Description:

This property specifies an image for an iCalendar object or 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. The "ALTREP" parameter, defined in [RFC5545], can be used to provide a "clickable" image where the URI in the parameter value can be "launched" by a click on the image in the calendar user agent.

Format Definition:

This property is defined by the following notation:

Example:

The following is an example of this property:

5.11. CONFERENCE Property

conference = "CONFERENCE" confparam  ":" uri CRLF

confparam  = *(
              ;
              ; The following is REQUIRED,
              ; but MUST NOT occur more than once.
              ;
              (";" "VALUE" "=" "URI") /
              ;
              ; The following are OPTIONAL,
              ; and MUST NOT occur more than once.
              ;
              (";" featureparam) / (";" labelparam) /
              ;
              ; The following is OPTIONAL,
              ; and MAY occur more than once.
              ;
              (";" other-param)
              ;
              )

CONFERENCE;VALUE=URI;FEATURE=PHONE,MODERATOR;
 LABEL=Moderator dial-in:tel:+1-412-555-0123,,,654321
CONFERENCE;VALUE=URI;FEATURE=PHONE;
 LABEL=Attendee dial-in:tel:+1-412-555-0123,,,555123
CONFERENCE;VALUE=URI;FEATURE=PHONE;
 LABEL=Attendee dial-in:tel:+1-888-555-0456,,,555123
CONFERENCE;VALUE=URI;FEATURE=CHAT;
 LABEL=Chat room:xmpp:chat-123@conference.example.com
CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO;
 LABEL=Attendee dial-in:https://chat.example.com/audio?id=123456

Property Name:

CONFERENCE

Purpose:

This property specifies information for accessing a conferencing system.

Value Type:

URI - no default.

Property Parameters:

IANA, non-standard, feature, and label property parameters can be specified on this property.

Conformance:

This property can be specified multiple times in a "VEVENT" or "VTODO" calendar component.

Description:

This property specifies information for accessing a conferencing system for attendees of a meeting or task. This might be a tel: URI [RFC3966] for a telephone-based conference number dial-in (with access codes included), or it might be an http: or https: URI [RFC7230] for a web-based video chat, or a URI for an instant messaging group chat room. If a specific URI for a conferencing system is not available, a data: URI [RFC2397] containing a text description can be used.

A conference system can be a bi-directional communication channel, or a uni-directional "broadcast feed".

The "FEATURE" property parameter is used to describe the key capabilities of the conference system to allow a client to choose the ones that give the required level of interaction from a set of multiple properties.

The "LABEL" property paramater is used to convey additional details on the use of the URI. For example, the URIs or access codes for the moderator and attendee of a teleconference system could be different, and the "LABEL" property parameter could be used to "tag" each "CONFERENCE" property to indicate which is which.

Format Definition:

This property is defined by the following notation:

Example:

The following are examples of this property:

6. Property Parameters

6.1. DISPLAY Property Parameter

displayparam = "DISPLAY" "=" displayval *("," displayval)

displayval =  ("BADGE" /     ; image inline with the title of the
                             ; event
               "GRAPHIC" /   ; a full image replacement for the event
                             ; itself
               "FULLSIZE" /  ; an image that is used to enhance the
                             ; event
               "THUMBNAIL" / ; a smaller variant of "FULLSIZE" to be
                             ; used when space for the image is
                             ; constrained
               x-name /      ; Experimental type
               iana-token)   ; Other IANA registered type
                             ;
                             ; Default is BADGE

IMAGE;VALUE=URI;DISPLAY=BADGE,THUMBNAIL;FMTTYPE=image/png:https://exa
 mple.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 "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:

6.2. EMAIL Property Parameter

emailparam = "EMAIL" "=" param-value

ATTENDEE;CN=Cyrus Daboo;EMAIL=cyrus@example.com:mailto:opaque-toke
 n-1234@example.com

Parameter Name:

EMAIL

Purpose:

To specify an email address that is used to identify or contact an organizer or attendee.

Format Definition:

This property parameter is defined by the following notation:

Description:

This property parameter MAY be specified on "ORGANIZER" or "ATTENDEE" properties. This property can be used in situations where the calendar user address value of "ORGANIZER" and "ATTENDEE" properties is not likely to be an identifier that recipients of scheduling messages could use to match the calendar user with, for example, an address book entry. The value of this property is an email address that can easily be matched by recipients. Recipients can also use this value as an alternative means of contacting the calendar user via email. If a recipient's calendar user agent allows the recipient to save contact information based on the "ORGANIZER" or "ATTENDEE" properties, those calendar user agents SHOULD use any "EMAIL" property parameter value for the email address of the contact over any mailto: calendar user address specified as the value of the property. Calendar user agents SHOULD NOT include an "EMAIL" property parameter when its value matches the calendar user address specified as the value of the property.

Example:

6.3. FEATURE Property Parameter

featureparam = "FEATURE" "=" featuretext *("," featuretext)
featuretext  =  ("AUDIO" /     ; Audio capability
                 "CHAT" /      ; Chat or instant messaging
                 "FEED" /      ; Blog or Atom feed
                 "MODERATOR" / ; Moderator dial-in code
                 "PHONE" /     ; Phone conference
                 "SCREEN" /    ; Screen sharing
                 "VIDEO" /     ; Video capability
                 x-name /      ; Experimental type
                 iana-token)   ; Other IANA registered type

CONFERENCE;VALUE=URI;FEATURE=AUDIO:rtsp://audio.example.com/
 event
CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO:https://video-chat.exam
 ple.com/;group-id=1234

Parameter Name:

FEATURE

Purpose:

To specify a feature or features of a conference or broadcast system.

Format Definition:

This property parameter is defined by the following notation:

Description:

This property parameter MAY be specified on the "CONFERENCE" property. Multiple values can be specified. The "MODERATOR" value is used to indicate that the property value is specific to the owner/initiator of the conference and contains a URI that "activates" the system (e.g., a "moderator" access code for a phone conference system that is different from the "regular" access code).

Example:

6.4. LABEL Property Parameter

labelparam = "LABEL" "=" param-value

CONFERENCE;VALUE=URI;FEATURE=VIDEO;
 LABEL="Web video chat, access code=76543";
 :https://video-chat.example.com/;group-id=1234

Parameter Name:

LABEL

Purpose:

To provide a human readable label.

Format Definition:

This property parameter is defined by the following notation:

Description:

This property parameter MAY be specified on the "CONFERENCE" property. It is anticipated that other extensions to iCalendar will re-use this property parameter on new properties that they define. As a result, clients SHOULD expect to find this property parameter present on many different properties. It provides a human readable label that can be presented to calendar users to allow them to discriminate between properties which might be similar, or provide additional information for properties that are not self-describing.

Example:

7. Security Considerations

Several of the new properties or parameters defined by this specification allow reference to "external" URIs. Care MUST be taken when accessing data at external URIs as malicious content could be present. In addition, access to those URIs could be tracked, leading to loss of privacy.

The "CONFERENCE" property can include a "FEATURE" property parameter with a "MODERATOR" value. In some cases the access code used by the owner/initiator of a conference might be private to an individual and clients and servers MUST ensure that such properties are not sent to attendees of a scheduled component, or sharees of a shared component.

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

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

8.3. Display Types Registry

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

8.4. Feature Types Registry

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

9. Acknowledgments

Thanks to the following for feedback: Bernard Desruisseaux, Mike Douglass, Lucia Fedorova, Ken Murchison, Arnaud Quillaud, and Dave Thewlis. This specification came about via discussions at the Calendaring and Scheduling Consortium.

10. References

10.1. Normative References

10.2. Informative References

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

Changes in draft-ietf-calext-extensions-03:

1. AD: fixed =/ ABNF syntax.
2. AD: added description for CATEGORIES.
3. AD: Removed extra / in image ABNF.
4. AD: Fixed VALUE=URI in image ABNF.
5. AD: Mention https in addition to http. Changed all examples to use https:
6. AD: fixed DISPLAY ABNF syntax.

Changes in draft-ietf-calext-extensions-02:

1. Refresh expired draft - no changes.

Changes in draft-ietf-calext-extensions-01:

1. Clarified difference between SOURCE and URL properties.
2. Use labelparam not infoparam.

Changes in draft-ietf-calext-extensions-00:

1. Document renamed after WG adoption.
2. Fixed tel: URI reference.

Changes in draft-daboo-icalendar-extensions-09:

1. Re-instated a trimmed down version of the CONFERENCE property after serious interest expressed by implementors.
2. LABEL property used instead of INFO - appropriated from another iCalendar draft.

Changes in draft-daboo-icalendar-extensions-08:

1. Trimmed down the display values to a minimal set.

Changes in draft-daboo-icalendar-extensions-07:

1. Removed ALTURI parameter - now use ALTREP.
2. Removed VALID property.
3. Removed TIMEZONE-ID property.
4. Added FULLSIZE and THUMBNAIL display values.
5. Added EMAIL property parameter.
6. Added LAST-MODIFIED property for use with VCALENDAR.
7. Added CATEGORIES property for use with VCALENDAR.
8. URL use now aligned with 5545.
9. Added SOURCE property.
10. COLOR now uses CSS3 values.

Changes in draft-daboo-icalendar-extensions-06:

1. Removed BROADCAST/CONFERENCE properties and related parameters.

Changes in draft-daboo-icalendar-extensions-05:

1. Added section with recommendation on handling extension properties.
2. Added VALID property.

Changes in draft-daboo-icalendar-extensions-04:

1. TZID changed to new property TIMEZONE-ID.
2. Minor formal syntax changes.

Changes in draft-daboo-icalendar-extensions-03:

1. Dropped CALENDAR- prefix
2. DESCRIPTION, UID and TZID now based on existing RFC5545 properties
3. COLOR now on both the calendar and component level
4. IMAGE now on both the calendar and component level
5. Added FEATURE and REGION parameters to CONFERENCE property
6. Added ALTURI parameter to IMAGE property
7. Added FEED value to FEATURE parameter
8. Added BROADCAST property and clarified that CONFERENCE is for bi-direction channels and BROADCAST is for uni-directional.

Changes in draft-daboo-icalendar-extensions-02:

1. Minor wording changes.
2. Interval is now described as the "minimum interval".
3. Added CONFERENCE property and INFO parameter.

Changes in draft-daboo-icalendar-extensions-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