This document updates the iCalendar (
© 2016 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 updates the iCalendar (
The iCalendar
This specification updates the iCalendar data model to support a new iCalendar component that can be used to represent just the changes in an overridden instance, rather than having to include everything describing it. This can significantly reduce the size of the iCalendar data, leading to reductions in network I/O (with resultant savings in battery usage on mobile devices), and storage requirements, on clients, servers, and associated databases.
This document updates the iCalendar (
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
The notation used in this memo is the ABNF notation of
Recurring events (or other types of component) in iCalendar are defined by the presence of “RRULE”, “RDATE”, and “EXDATE” properties in a “master component”. Those rules produce a set of “generated instances”. “Generated instances” do not need to have a representation in the iCalendar data, as their content can be inferred from the “master component”. In some cases specific “generated instances” are changed, resulting in an “overridden instance”. An “overridden instance” is represented in iCalendar as an “overridden component”, which has the same “UID” property value as the “master component”, and a “RECURRENCE-ID” property whose value matches the start time of the corresponding “generated instance” (which can be different from the actual start time of the “overridden instance”).
For example, consider the following daily recurring event, with no overridden instances. This event defines a set of generated instances for 20160902, 20160903, 20160904, etc.
If the summary of the second instance needs to be changed, the resulting iCalendar object would be:
As can be seen, the overridden component for 20160903 duplicates many iCalendar properties from the master component, with the “SUMMARY” property being different, “RECURRENCE-ID” added, and “DTSTART” adjusted to the start time of the instance. All the other properties are the same as the corresponding ones in the master component. Using the new representation described by this specification, this iCalendar object would appear as:
In this case the “VINSTANCE” component is used to encapsulate just those iCalendar properties that are different from the generated instance — just “SUMMARY” in this case. The new representation is just over 80% of the size of the traditional representation, giving a small, but not insignificant, reduction in size. But as more overrides are needed, or as more properties are added to the master component, the savings will increase dramatically.
This specification defines the new “VINSTANCE” component, which is used to represent just the differences between a generated instance, derived from the master component, and the actual overridden instance that will be used instead of the generated instance.
“VINSTANCE” components MUST only appear as sub-components within master components (e.g., they can only appear as sub-components of components that include at least one of either “RRULE” or “RDATE” properties).
Each “VINSTANCE” component MUST include a “RECURRENCE-ID” property with a value that identifies the instance being overridden. Multiple “VINSTANCE” components can appear within a single master component, but each MUST have a unique “RECURRENCE-ID” property value. Unlike traditional overridden components, “VINSTANCE” components MUST NOT include a “UID” property (the effective “UID” is that of the master component enclosing the “VINSTANCE” component).
The iCalendar components and properties within a “VINSTANCE” component are interpreted as follows:
Any component appearing in “VINSTANCE” is treated as an addition or update to the corresponding generated instance (see
Any property (excluding “RECURRENCE-ID” and “INSTANCE-DELETE”) appearing in “VINSTANCE” is treated as an addition or update to the corresponding generated instance (see
Any “INSTANCE-DELETE” property appearing in “VINSTANCE” indicates the removal of a component or property from the corresponding generated instance (see
All sub-components in the master component MUST have a “UID” property with a value that is unique (at least within that master component). This allows such sub-components to be easily identified for the purposes of indicating whether a “VINSTANCE” is adding, updating, or deleting a sub-component.
Any iCalendar component defined in the “VINSTANCE” component (referred to here as the “instance component”), other than a “PATCH” component [draft-patch], is treated as either an addition to the generated instance, or as an update of an existing component in the generated instance, as follows:
If the generated instance does not contain a sub-component with a “UID” property value matching that of the instance component, then the instance component is an addition to the generated instance.
If a sub-component of the generated instance contains a “UID” property with a value that matches that of the instance component, then the instance component replaces the matching one in the generated instance.
Alternatively, a sub-component can be “incrementally” updated by use of a “PATCH” component [draft-patch] that targets the sub-component. A “PATCH” component is created by determining the difference between the sub-component in the overridden instance and the matching sub-component in the generated instance. The “PATCH-TARGET” property value in the “PATCH” component is specified as a path relative to the overridden component targeting the sub-component by its “UID” property value (e.g., if a “VALARM” component inside a “VEVENT” component is being updated, the “PATCH-TARGET” property value would be “/VALARM[UID=1234]” (assuming that the “UID” property value of the sub-component being updated is “1234”). The “PATCH” component is then added as a sub-component of the “VINSTANCE” component representing the overridden instance.
When expanding a “VINSTANCE” component into an overridden component, any “PATCH” sub-components are used to update sub-components in the generated instance, by applying the patch processing rules to those sub-components.
Any iCalendar property (other than “RECURRENCE-ID” and “INSTANCE-DELETE”) defined in the “VINSTANCE” component (referred to here as the “instance property”) is treated as either an addition to the generated instance, or as an update of an existing property in the generated instance. A “INSTANCE-ACTION”
If the instance property does not contain an “INSTANCE-ACTION” property parameter, or contains an “INSTANCE-ACTION” property parameter with the default value “BYNAME”, then all properties with the same name in the generated instance are replaced by the instance property.
If the instance property contains an “INSTANCE-ACTION” property parameter with the value “CREATE”, then the instance property is added to the generated instance.
If the instance property contains an “INSTANCE-ACTION” property parameter with the value “UPDATE”, then all properties with the same name and same value in the generated instance have their parameters updated or removed as follows: .. Any parameter name appended to the “UPDATE” parameter value with a “~” separator is used to remove matching parameters from the derived instance. .. Any parameters, other than “INSTANCE-ACTION”, replace any parameters with the same name in the derived instance, or are added to the derived instance if no there is no parameter with the same name.
If the instance property contains an “INSTANCE-ACTION” property parameter with the value starting with “BYPARAM”, then all properties with the same name and a property parameter that matches the one that is part of the “INSTANCE-ACTION” property value, in the generated instance are replaced by the instance property.
The “INSTANCE-ACTION=BYNAME” operation is used for adding or updating “singleton” properties — properties that only appear once in a given iCalendar component (e.g., “DTSTART”, “DTEND”, “LOCATION”, etc).
The “INSTANCE-ACTION=CREATE” operation is used for adding “multi-occurring” properties — properties that can appear more than once in a given iCalendar component (e.g., “ATTENDEE”, “ATTACH”, “EXDATE”, etc).
The “INSTANCE-ACTION=UPDATE” operation is used for updating parameters on a specific “multi-occurring” property that can be uniquely identified by its value (e.g., the “ATTENDEE” property can appear multiple times in a “VEVENT” component, but each property will have a unique value in that component). This operation cannot be used when the value of the property is being changed. Instead, the “INSTANCE-ACTION=BYPARAM” operation can be used to identify the property being replaced.
The “INSTANCE-ACTION=BYPARAM” operation is used for updating a specific “multi-occurring” property that can be uniquely identified by a parameter value that is the same as one in the instance property.
There may be some situations where a multi-occurring property cannot be uniquely identified. In such cases, the solution to updating one or more of them is to use an “INSTANCE-ACTION=BYNAME” to replace all the existing properties with one new one, then use “INSTANCE-ACTION=CREATE” to add back others that are unchanged or also being updated. Whilst this is not ideal, it is anticipated that these situations can be avoided by adding appropriate property parameters with unique values to help disambiguate the multi-occurring properties.
The “INSTANCE-DELETE” property (defined in
The following operations are supported:
the “INSTANCE-DELETE” path value identifies components only. The matching components are removed from the generated instance.
the “INSTANCE-DELETE” path value identifies properties only. The matching properties are removed from the generated instance.
This specification makes use of the concept of an “iCalendar path” defined in Section XX of [draft-patch]. This specification only makes use of “relative” paths to identify components or properties directly within a generated instance.
VINSTANCE
Provide components and properties that are used to indicate the difference between a generated instance and an actual overridden instance.
A “VINSTANCE” calendar component is defined by the following notation:
This component is used to define an overridden instance of a master component that can include changes to the generated instance, such as component or property additions updates, or deletions. See
INSTANCE-DELETE
This property specifies a relative path identifying one or more components or properties to be removed from a generated instance.
TEXT
IANA and nonstandard property parameters can be specified on this property.
This property can be specified within a “VINSTANCE” component only.
This property is used to match iCalendar components or properties that will be deleted. The path value is always a relative path for only immediate components and properties within the generated instance, and interpreted as described in
This property is defined by the following notation:
The following are examples of this property:
INSTANCE-ACTION
To specify whether the property should be added or replaced.
This property parameter can be specified on properties contained in a “VINSTANCE” component and MUST NOT be specified on properties outside of a “VINSTANCE” component. This property parameter specifies whether the associated property should be added to the generated instance or should replace existing properties in the generated instance. In the latter case, the property parameter also specifies how to match existing properties. The processing of this property parameter is described in
This parameter is defined by the following notation:
The following are examples of this property parameter:
Any iCalendar processing engine that supports “VINSTANCE” is allowed to convert between the traditional overridden component representation and the “VINSTANCE” based representation when processing iCalendar data. However, iCalendar data SHOULD NOT mix traditional and “VINSTANCE” based representations in the same iCalendar object. However, when iCalendar data is transferred to another system whose support for “VINSTANCE” cannot be confirmed, the iCalendar data being transferred MUST be converted into its traditional overridden component representation.
iTIP
The CalDAV
TBD define protocol changes required in clients and servers to allow negotiated use of VINSTANCE.
[draft-patch] defines how iCalendar data can updated using a “patch” component that defines the changes between the original and updated data. This generic mechanism works with the new “VINSTANCE” representation introduced by this specification.
However, [draft-patch] does define an “implicit” recurrence override mechanism, whereby a patch operation can implicitly create an overridden component in an iCalendar object by only including components and/or properties that are different from the generated instance. An example of an implicit override patch is shown in
Security considerations described in
Privacy considerations described in
This document defines the following new iCalendar components to be added to the registry defined in
| Component | Status | Reference |
|---|---|---|
| VINSTANCE | Current | RFCXXXX, |
This document defines the following new iCalendar properties to be added to the registry defined in
| Property | Status | Reference |
|---|---|---|
| INSTANCE-DELETE | Current | RFCXXXX, |
This document defines the following new iCalendar parameters to be added to the registry defined in
| Property | Status | Reference |
|---|---|---|
| INSTANCE-ACTION | Current | RFCXXXX, |
A new IANA registry for iCalendar elements has been added. Additional codes MAY be used, provided the process described in
The following table has been used to initialize the Instance Action Registry:
| Instance Action | Status | Reference |
|---|---|---|
| CREATE | Current | RFCXXXX, |
| UPDATE | Current | RFCXXXX, |
| BYNAME | Current | RFCXXXX, |
| BYPARAM | Current | RFCXXXX, |
Thanks to the following for feedback: Michael Douglass, Ken Murchison.
This specification originated from work at the Calendaring and Scheduling Consortium, which has helped with the development and testing of implementations.
This variant shows the “VALARM” being updated by using a “PATCH” component as opposed to include the entire “VALARM” component.
This examples shows two overridden instances. The first one covers the case where an attendee has accepted all but one instance of a recurring meeting, with the one instance being declined. The second one covers the case where an attendee has responded only to one instance of a recurring meeting, with the other instances still waiting for a response.
This example shows the implicit addition of an overridden component which has only its “SUMMARY” property changed, via a patch operation.
Before:
Patch:
After:
This example shows the explicit addition of an overridden instance using a “VINSTANCE” component, via a patch operation.
Before:
Patch:
After:
This example shows the implicit addition of an overridden instance using a “VINSTANCE” component, via a patch operation.
Before:
Patch:
After:
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]
Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [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 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]