This document defines a set of extensions to the iCalendar VALARM component to enhance use of alarms and improve interoperability between clients and servers.
© 2024-07-23 The Calendaring and Scheduling Consortium, Inc.
This document is not a CalConnect Standard. It is distributed for review and comment, and is subject to change without notice and may not be referred to as a Standard. Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior written permission. Permission can be requested from the address below.
The Calendaring and Scheduling Consortium, Inc.
4390 Chaffin Lane
McKinleyville
California 95519
United States of America
www.calconnect.org
This document defines a set of extensions to the iCalendar VALARM component to enhance use of alarms and improve interoperability between clients and servers.
The iCalendar
As iCalendar has become more widely used and as client-server protocols such as CalDAV
This specification defines a set of extensions to “VALARM” components to cover common requirements for alarms not currently addressed in iCalendar. Each extension is defined in a separate section below. For the most part, each extension can be supported independently of the others, though in some cases one extension will require another. In addition, this specification describes mechanisms by which clients can interoperably implement common features such as “snoozing”.
This document defines a set of extensions to the iCalendar VALARM component to enhance use of alarms and improve interoperability between clients and servers.
No terms and definitions are listed 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 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
When XML element types in the namespaces “DAV:” and “urn:ietf:params:xml:ns:caldav” are referenced in this document outside of the context of an XML fragment, the string “DAV:” and “CALDAV:” will be prefixed to the element type names respectively.
A “VALARM” calendar component is re-defined by the following notation:
This extension adds a “UID” property to “VALARM” components to allow a unique identifier to specified. The value of this property can then be used to refer uniquely to the “VALARM” component.
The “UID” property defined here follows the definition in
The “VALARM” component defined in
It is often convenient to relate one or more “VALARM” components to other “VALARM” components (e.g., see
This specification updates the usage of the “RELATED-TO” property defined in
The “VALARM” component defined in
There is currently no way for a “VALARM” component to indicate whether it has been triggered and acknowledged. With the advent of a standard client/server protocol for calendaring and scheduling data (
Also, with recurring events that have alarms, it is important to know when the last alarm in the recurring set was acknowledged, so that the client can determine whether past alarms have been missed.
To address these needs, this specification adds an “ACKNOWLEDGED” property to “VALARM” components to indicate when the alarm was last sent or acknowledged. This is defined by the syntax below.
ACKNOWLEDGED
This property specifies the UTC date and time at which the corresponding alarm was last sent or acknowledged.
DATE-TIME
IANA and non-standard property parameters can be specified on this property.
This property can be specified within “VALARM” calendar components.
This property is used to specify when an alarm was last sent or acknowledged. This allows clients to determine when a pending alarm has been acknowledged by a calendar user so that any alerts can be dismissed across multiple devices. It also allows clients to track repeating alarms or alarms on recurring events or to-dos to ensure that the right number of missed alarms can be tracked.
Clients SHOULD set this property to the current date-time value in UTC when a calendar user acknowledges a pending alarm. Certain kinds of alarm may not provide feedback as to when the calendar user sees them, for example email based alerts. For those kinds of alarms, the client SHOULD set this property when the alarm is triggered and the action successfully carried out.
When an alarm is triggered on a client, clients can check to see if an “ACKNOWLEDGED” property is present. If it is, and the value of that property is greater than or equal to the computed trigger time for the alarm, then the client SHOULD NOT trigger the alarm. Similarly, if an alarm has been triggered and an “alert” presented to a calendar user, clients can monitor the iCalendar data to determine whether an “ACKNOWLEDGED” property is added or changed in the alarm component. If the value of any “ACKNOWLEDGED” property in the alarm changes and is greater than or equal to the trigger time of the alarm, then clients SHOULD dismiss or cancel any “alert” presented to the calendar user.
This property is defined by the following notation:
The following is an example of this property:
Users often want to “snooze” an alarm, and this specification defines a standard approach to accomplish that.
To “snooze” an alarm, clients create a new “VALARM” component within the parent component of the “VALARM” that was triggered and is being “snoozed” (i.e., as a “sibling” component of the “VALARM” being snoozed). The new “VALARM” MUST be set to trigger at the user’s chosen “snooze” interval after the original alarm triggered. Clients SHOULD use an absolute “TRIGGER” property with a “DATE-TIME” value specified in UTC.
Clients SHOULD add a “RELATED-TO” property to the new “VALARM” component with a value set to the “UID” property value of the “VALARM” component being snoozed. If the “VALARM” component being snoozed does not already have a “UID” property, the client SHOULD add one. The “RELATED-TO” property added to the new “VALARM” component SHOULD include a “RELTYPE” property parameter with a value set to “SNOOZE”.
When the “snooze” alarm is triggered and dismissed the client SHOULD remove the corresponding “VALARM” component, or set the “ACKNOWLEDGED” property (see
This specification adds the “SNOOZE” relationship type for use with the “RELTYPE” property defined in
VALARMs are currently triggered when a specific date-time is reached. It is also desirable to be able to trigger alarms based on location, e.g. when arriving at or departing from a particular location.
This specification adds the following properties to “VALARM” components to indicate when an alarm can be triggered based on location.
“PROXIMITY” — indicates that a location based trigger is to be used and which direction of motion is used for the trigger
“STRUCTURED-LOCATION” — used to indicate the actual location to trigger off, specified using a geo: URI
Typically, when a “PROXIMITY” property is used there is no need to specify a time-based trigger using the “TRIGGER” property. However, since “TRIGGER” is defined as a required property for a “VALARM” component, for backwards compatibility it has to be present, but ignored. To indicate a “TRIGGER” that is to be ignored, clients SHOULD use a value a long time in the past. A value of “19760401T005545Z” has been commonly used for this purpose.
PROXIMITY
This property indicates that a location based trigger is applied to an alarm.
TEXT
IANA and non-standard property parameters can be specified on this property.
This property can be specified within “VALARM” calendar components.
This property is used to indicate that an alarm has a location-based trigger. Its value identifies the direction of motion used to trigger the alarm. One or more location values are set using “STRUCTURED-LOCATION” properties.
When the property value is set to “ARRIVE”, the alarm is triggered when the calendar user agent arrives in the vicinity of any of the specified locations. When set to “DEPART”, the alarm is triggered when the calendar user agent departs from the vicinity of any specified locations.
When the property value is set to “CONNECT”, the alarm is triggered when the calendar user agent connects to a
This property is defined by the following notation:
The following is an example of this property:
The following example shows a “VALARM” component with a proximity trigger set to trigger when the device running the calendar user agent leaves the vicinity defined by the structured location property. Note use of the “u=” parameter with the “geo” URI to define the precision of the location determination.
VALARMs, if not monitored properly, can be used to “spam” users and/or leak personal information. For instance, an unwanted audio or display alert could be considered spam. Or an email alert could be used to leak a user’s location to a third party or to send unsolicited email to multiple users. Therefore, CalDAV clients and servers that accept iCalendar data from a third party (e.g. via
Proximity VALARMs, if not used carefully, can leak a user’s past, present, or future location. For instance, storing an iCalendar resource containing proxmity VALARMs to a shared calendar on CalDAV server can expose to anyone that has access to that calendar the user’s intent to leave from or arrive at a particular location at some future time. Furthermore, if a CalDAV client updates the shared iCalendar resource with an ACKNOWLEDGED property when the alarm is triggered, will leak the exact date and time that the user left from or arrived at the location.
Therefore, CalDAV clients that implement proximity alarms SHOULD give users the option of storing and/or acknowledging the alarms on the local device only and not storing the alarm and/or acknowledgment on a remote server.
This document defines the following new iCalendar properties to be added to the registry defined in
| Property | Status | Reference |
|---|---|---|
| ACKNOWLEDGED | Current | RFCXXXX, |
| PROXIMITY | Current | RFCXXXX, |
This document defines the following new iCalendar relationship type to be added to the registry defined in
| Relationship Type | Status | Reference |
|---|---|---|
| SNOOZE | Current | RFCXXXX, |
This document creates a new iCalendar registry for values of the “PROXIMITY” property:
| Value | Status | Reference |
|---|---|---|
| ARRIVE | Current | RFCXXXX, |
| DEPART | Current | RFCXXXX, |
| CONNECT | Current | RFCXXXX, |
| DISCONNECT | Current | RFCXXXX, |
This specification came about via discussions at the Calendaring and Scheduling Consortium. Also, thanks to the following for providing feedback: Bernard Desruisseaux, Mike Douglass, Jacob Farkas, Jeffrey Harris, and Ciny Joy.
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
This document defines extensions to the Web Distributed Authoring and Versioning (WebDAV) protocol to specify a standard way of accessing, managing, and sharing calendaring and scheduling information based on the iCalendar format. This document defines the “calendar-access” feature of CalDAV. [STANDARDS-TRACK]
This document defines the iCalendar data format for representing and exchanging calendaring and scheduling information such as events, to-dos, journal entries, and free/busy information, independent of any particular calendar service or protocol. [STANDARDS-TRACK]
This document specifies a Uniform Resource Identifier (URI) for geographic locations using the ‘geo\’ scheme name. A ‘geo’ URI identifies a physical location in a two- or three-dimensional coordinate reference system in a compact, simple, human-readable, and protocol-independent way. The default coordinate reference system used is the World Geodetic System 1984 (WGS-84). [STANDARDS-TRACK]
This document defines a set of new properties for iCalendar data and extends the use of some existing properties to the entire iCalendar object.
RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.
This document specifies a protocol that uses the iCalendar object specification to provide scheduling interoperability between different calendaring systems. This is done without reference to a specific transport protocol so as to allow multiple methods of communication between systems. Subsequent documents will define profiles of this protocol that use specific, interoperable methods of communication between systems.
The iCalendar Transport-Independent Interoperability Protocol (iTIP) complements the iCalendar object specification by adding semantics for group scheduling methods commonly available in current calendaring systems. These scheduling methods permit two or more calendaring systems to perform transactions such as publishing, scheduling, rescheduling, responding to scheduling requests, negotiating changes, or canceling. [STANDARDS-TRACK]