Added XML schema; fixed a number of minor issues.
Clarified a number of issues; cleaned up specification.
First (semi) complete version supporting all use cases.
First rough draft.
The &rfc3283; describes the relationship between various internet calendaring specifications like this: "&rfc2445; is the language used to describe calendar objects. &rfc2446; (Transport-Independent Interoperability Protocol) describes a way to use the iCalendar language to do scheduling. &rfc2447; (Message-Based Interoperability Protocol) describes how to do iTIP scheduling via e-mail."
Recently another standard track protocol for calendar and scheduling access has appeared. &rfc4791; (Calendaring Extensions to WebDAV) is a &rfc4918; (Web-based Distributed Authoring and Versioning) based mechanism for manipulating internet calendars, and viewing free/busy lists, and via a planned &draft-sched;, could be used for proposing calendar events as well.
This specification defines calendaring extensions to &xep0060; for the purposes of group calendaring and scheduling between "Calendar Users" (CUs) as defined by iTIP. Additionally, it defines extensions for accessing, managing, and sharing calendaring and scheduling information on a calendar server, reusing the syntax and semantics defined by CalDAV. Finally, it defines a mechanism for reminding of upcoming events by alarm notifications.
The protocol enables all common transactions such as publish, schedule, reschedule, respond to scheduling requests, negotiation of changes or cancel iCalendar-based calendar components, as well as search for busy time information. The protocol is a superset of Publish-Subscribe and will gracefully degrade to Publish-Subscribe for clients that do not support the calendaring extensions defined.
This specification follows the same pattern as the Internet calendaring and scheduling standards by developing all features based on a well-described data model. This model is described in Calendaring Data Model. As a brief overview, calendars are modeled as nodes of a calendaring-aware publish-subscribe service; each calendar node contains a number of items representing calendar objects. Each item representing a calendar object (event, to-do, journal entry, or other calendar components) is called a "calendar item".
Calendar objects are represented using &draft-xcal;. The format is not an alternative or next generation of iCalendar but defines how to use XML to represent iCalendar objects in XML. For example, both examples below describe the same single event that begins on July 14, 1997 at 00:00 UTC and ends on July 15, 1997 at 03:59 UTC.
This specification is structured as follows: Discovering Support describes how to discover support for the calendaring extensions defined by this specification. An entity may create new calendar nodes as described in Creating Calendars. The section on Scheduling Calendar Entries provides the transport specific information necessary to convey iTIP messages over Publish-Subscribe which enables transactions such as publish, schedule, reschedule, respond to scheduling requests, negotiation of changes or cancel iCalendar-based calendar components. The sections Retrieving Calendar Entries and Retrieving Free/Busy Time define how to retrieve items from a calendar node, and how to search for busy time information. Alarm Notifications provide a mechanism for setting up and subscribing to alarm notifications.
In order to refer to elements of the calendaring and scheduling model, core object or interoperability protocol defined in RFC 2445 and RFC 2446 several formatting conventions have been utilized.
Calendaring and scheduling roles are referred to in quoted-strings of text with the first character of each word in upper case. For example, "Organizer" refers to a role of a "Calendar User" (CU) within the scheduling protocol defined by RFC 2446.
Scheduling methods defined by RFC 2446 are referred to with capitalized, quoted-strings of text. For example, "REQUEST" refers to the method for requesting a scheduling calendar component be created or modified, "REPLY" refers to the method a recipient of a request uses to update their status with the "Organizer" of the calendar component.
Calendar components defined by RFC 2445 are referred to with capitalized text. All calendar components start with the letter "V". For example, VEVENT refers to the event calendar component, VTODO refers to the to-do calendar component and VJOURNAL refers to the daily journal calendar component.
Properties defined by RFC 2445 are referred to with capitalized, quoted-strings of text, followed by the word "property". For example, "ATTENDEE" property refers to the iCalendar property used to convey the calendar address of a "Calendar User". Property parameters are referred to with lower case, quoted-strings of text, followed by the word "parameter". For example, "value" parameter refers to the iCalendar property parameter used to override the default data type for a property value. Values are referred to with quoted-strings of text, either alone or followed by the word "value".
Implementers will need to be familiar with several other specifications that describe the Internet calendaring and scheduling standards. The related documents are:
This specification is an extension of the Publish-Subscribe protocol specified by XEP-0060, so implementers will need to be familiar with that as well.
This specification does not attempt to repeat the specification of concepts or definitions from these other specifications. Where possible, references are made to the specification that provides that provides the relevant concepts or definitions.
A calendar service is a calendaring-aware engine combined with a publish-subscribe service. A publish-subscribe service enables XMPP entities to create nodes and publish information at those nodes; an event notification (with or without payload) is then broadcasted to all entities that have subscribed to the node.
A calendar service MAY include calendar data in some of its nodes, and non-calendaring data in others.
A publish-subscribe service can advertise itself as a calendar service if it supports the functionality defined in this specification at any of its nodes. That might mean that calendar nodes are spread throughout the service and mixed with non-calendar nodes. Calendaring features are only required in the nodes that are calendar nodes.
The calendar service is the canonical location for calendar data and state information. Entities may submit requests to change data or download data. Entities may store calendar objects offline and attempt to synchronize at a later time. However, entities MUST be prepared for calendar data on the service to change between the time of last synchronization and when attempting an update, as calendar nodes may be shared and accessed by multiple entities.
A calendar node contains calendar items that represent calendar components within a calendar. A calendar node is manifested to entities as a publish-subscribe node identified by a NodeID. A calendar node MUST report the '&NS;' feature &VNOTE; in the result of a 'disco#info' query. A calendar service MUST persist items for a calendar node.
A calendar node can be created through provisioning (i.e., automatically created when a user's account is provisioned), or it can be created with the publish-subscribe <create/> request (see section Creating Calendars). It can be useful for a user to create additional calendars (e.g., soccer schedule) or for users to share a calendar (e.g., team events or conference rooms). However, note that this specification doesn't define the purpose of calendar nodes. Users may use the 'pubsub#title' and 'pubsub#description' fields in node meta-data to find out what a calendar node is for.
Calendar nodes MUST only contain calendar items. This ensures that entities do not have to deal with non-calendar data in a calendar node.
Calendar items in a calendar node MUST NOT contain more than one type of calendar component (e.g., VEVENT, VTODO, VJOURNAL, VFREEBUSY, etc.) with the exception of VTIMEZONE components, which MUST be specified for each unique "TZID" parameter value specified in the iCalendar object. For instance, a calendar item can contain one VEVENT component and one VTIMEZONE component, but it cannot contain one VEVENT component and one VTODO component. Instead, the VEVENT and VTODO components would have to be stored in separate calendar items in the same node.
Calendar object items in calendar collections MUST NOT specify the iCalendar "METHOD" property.
The "UID" property value of the calendar components contained in a calendar item MUST be unique in the scope of the calendar node in which they are stored.
Calendar components in a calendar node that have different "UID" property values MUST be stored in separate calendar items.
Calendar components with the same "UID" property value, in a given calendar node, MUST be contained in the same calendar item. This ensures that all components in a recurrence "set" are contained in the same calendar item. It is possible for a calendar item to just contain components that represent "overridden" instances (ones that modify the behavior of a regular instance, and thus include a "RECURRENCE-ID" property) without also including the "master" recurring component (the one that defines the recurrence "set" and does not contain any "RECURRENCE-ID" property).
This specification uses methods defined by RFC 2446 for exchanging calendar objects for the purposes of group calendaring and scheduling between "Calendar Users" (CUs). CUs take on one of two roles in iTIP. The CU who initiates an exchange takes on the role of "Organizer". For example, the CU who proposes a group meeting is the "Organizer". The CUs asked to participate in the group meeting by the "Organizer" take on the role of "Attendee".
Note: "role" is also a descriptive parameter to the "ATTENDEE" property. Its use is to convey descriptive context to an "Attendee" such as "chair", "req-participant" or "non-participant" and has nothing to do with the calendaring workflow.
A calendar entry is created and managed by an "Organizer". The "Organizer" interacts with other CUs by sending one or more requests specifying the "REQUEST" method to a calendar service which will forward these to "Attendees" (and send notifications to pubsub subscribers). "Attendees" use the same requests specifying the "REPLY" method to communicate their status back to the calendar service. "Attendees" cannot make any changes to the calendar entry except for their own status. They can, however, use requests specifying the "COUNTER" method to suggest changes to the "Organizer". In any case, the "Organizer" has complete control over the master calendar entry.
| Method | Description |
|---|---|
| PUBLISH | Used to publish a calendar object to a calendar node and when sending notifications to pubsub subscribers. There is no interactivity between the publisher and any other calendar user. An example might include a baseball team publishing its schedule to the public. |
| REQUEST | Used to schedule a calendar entry with other Calendar Users. Requests are interactive in that they require the receiver to respond using the Reply methods. Invitations and the assignment of To-Dos to other Calendar Users are examples. Requests are also used by the "Organizer" to update the status of a calendar entry. |
| REPLY | A Reply is used in response to a Request to convey "Attendee" status to the calendar service (which will forward it to the "Organizer"). Replies are commonly used to respond to meeting and task requests. |
| ADD | Add one or more instances to an existing VEVENT, VTODO, or VJOURNAL. |
| CANCEL | Cancel one or more instances of an existing VEVENT, VTODO, or VJOURNAL. This does not remove the calendar entry from persistent storage. |
| COUNTER | The Counter method is used by an "Attendee" to negotiate a change in the calendar entry. Examples include the request to change a proposed Event time or change the due date for a To-Do. |
The methods listed above and their usage and semantics are defined in section 3 of RFC 2446.
The other methods defined by RFC 2446, REFRESH and DECLINECOUNTER, are not used and MUST NOT be specified by requesting entities. Entities SHOULD use the reporting methods defined in this specification to request the latest version of a calendar entry. "Organizers" MAY decline a proposed counter-proposal by sending a rude chat message to the "Attendee" who proposed the counter-proposal.
Subscriptions to a calendar node may exist in three different ways.
&TODO;
Group scheduling is accomplished using the set of "request" and "response" methods described above. To manage permissions, this specification builds on the hierarchy of affiliations defined by XEP-0060. Therefore, a calendar service MUST support and adhere to the requirements of pubsub affiliations. Calendaring permissions are calculated from the pubsub affiliation of the XMPP entity and, if applicable, the properties of the calendar item involved in an operation.
&TODO;
There are two distinct states relevant to calendar entries: the overall state of the entry and the state associated with an "Attendee" to that entry.
The state of an entry is defined by the "STATUS" property and is controlled by the "Organizer." There is no default value for the "STATUS" property. The "Organizer" sets the "STATUS" property to the appropriate value for each calendar entry.
The state of a particular "Attendee" relative to an entry is defined by the "partstat" parameter in the "ATTENDEE" property for each "Attendee". When an "Organizer" issues the initial entry, "Attendee" status is unknown. The "Organizer" specifies this by setting the "partstat" parameter to "needs-action". Each "Attendee" modifies their "ATTENDEE" property "partstat" parameter to an appropriate value.
The "SEQUENCE" property is used by the "Organizer" to indicate revisions to the calendar item. The rules for incrementing the "SEQUENCE" number for a given "UID" in a calendar component are as follows:
The value of the "SEQUENCE" property contained in a response from an "Attendee" may not always match the current revision of the master calendar entry. Implementations may choose to indicate to the "Attendee" that the response is to an entry that has been revised and allow the CU to decide whether or not to send the response.
Calendar services must often correlate a component in a calendar node with a component received in a pubsub request. For example, an event may be updated with a later revision of the same event. To accomplish this, a calendar service must correlate the version of the event already in the calendar node with the version sent in the pubsub request. In addition to this correlation, there are several factors that can cause requests to arrive in an unexpected order. That is, a calendar service could receive a reply to an earlier revision of a component AFTER receiving a reply to a later revision.
To maximize interoperability and to handle messages that arrive in an unexpected order, implementations SHOULD follow the rules in section 2.1.5 of RFC 2446. Hence, a calendar service must persist the following component properties: "UID", "RECURRENCE-ID", "SEQUENCE", and "DTSTAMP". Furthermore, for each "ATTENDEE" property of a component a calendar service must persist the "SEQUENCE" and "DTSTAMP" property values associated with the "Attendee's" response.
A calendar service MUST respond to service discovery information requests qualified by the 'http://jabber.org/protocol/disco#info' namespace. The "disco#info" result returned by a calendar service MUST indicate the identity of a pubsub service and indicate which pubsub features are supported. A calendar service supporting the features described in this specification MUST also include "&NS;" as a feature in the "disco#info" result. A feature of "&NS;" &VNOTE; in the result MUST indicate that the service supports all MUST level requirements in this specification.
A calendar service MUST also allow entities to query individual nodes for the information associated with that node. A calendar service supporting the features described in this specification MUST include "&NS;" &VNOTE; as a feature in the "disco#info" result for a calendar node. It MUST NOT include the feature in the result for a non-calendar node. The "disco#info" result MAY include detailed meta-data about the node as described in section 5.4 of XEP-0060.
An entity may want to create a new calendar node. Support for this feature is RECOMMENDED. However, a calendar service MAY disallow creation of calendar nodes based on the identity of the requesting entity, or MAY disallow calendar node creation altogether (e.g., reserving that privilege to a service-wide administrator).
The methods to create a node are explained in section 8.1 of XEP-0060. To create a new calendar node, the requesting entity MUST include a Data Form containing a 'pubsub#type' field whose <value/> is "urn:ietf:params:xml:ns:xcal".
If calendar nodes are supported and none of the general or method-specific errors has occurred, the calendar service SHOULD create the node and inform the requesting entity of success.
In addition to the errors already defined for leaf nodes by XEP-0060, there are several reasons why the calendar node creation request might fail:
These error cases are described more fully in the following sections.
If the calendar service does not allow new calendar nodes to be created, it MUST respond with a ¬allowed; error.
If the requesting entity has insufficient privileges to create new calendar nodes, the service MUST respond with a &forbidden; error.
A calendar service MUST offer a couple of node configuration options that are specific to calendar nodes and not provided by standard pubsub leaf nodes. The following table shows these configuration options and defines a mapping to the calendar properties specified by RFC 4791:
| Configuration option | Type | Description | CalDAV property |
|---|---|---|---|
| pubsub#title | text-single | Provides a human-readable description of the calendar node. | calendar-description |
| &SN;#timezone | text-single | Specifies a time zone on a calendar node. | calendar-timezone |
| &SN;#component_set | text-multi | Specifies the calendar component types (e.g., VEVENT, VTODO, etc.) that calendar items can contain in the calendar node. | supported-calendar-component-set |
| pubsub#type | text-single | Specifies what media types are allowed for calendar items in a calendar node. | supported-calendar-data |
| pubsub#max_payload_size | text-single | Provides a numeric value indicating the maximum size of a resource in octets that the calendar service is willing to accept when a calendar item is stored in a calendar node. | max-resource-size |
| &SN;#min_date_time | text-single | Provides a DATE-TIME value indicating the earliest date and time (in UTC) that the calendar service is willing to accept for any DATE or DATE-TIME value in a calendar item stored in a calendar node. | min-date-time |
| &SN;#max_date_time | text-single | Provides a DATE-TIME value indicating the latest date and time (in UTC) that the calendar service is willing to accept for any DATE or DATE-TIME value in a calendar item stored in a calendar node. | max-date-time |
| &SN;#max_instances | text-single | Provides a numeric value indicating the maximum number of recurrence instances that a calendar item stored in a calendar node can generate. | max-instances |
| &SN;#max_attendees_per_instance | text-single | Provides a numeric value indicating the maximum number of "ATTENDEE" properties in any instance of a calendar item stored in a calendar node. | max-attendees-per-instance |
An entity SHOULD should specify the 'pubsub#title' field for a human-readable name of the calendar when configuring a calendar node. The entity SHOULD NOT set the 'pubsub#title' field to be the same as any other calendar node owned by the same entity. When displaying calendar nodes to users, clients SHOULD check the 'pubsub#title' field and use that value as the name of the calendar. In the event that the 'pubsub#title' field is empty, the client MAY use the NodeID of the calendar as the name; however, the NodeID may be "opaque" and not represent any meaningful human-readable text.
An entity may schedule calendar entries by sending a <publish/> request to the calendar service. Support for this feature is REQUIRED.
The syntax is as follows:
The example below publishes a single event that begins on July 1, 1997 at 20:00 UTC. This event contains the minimum set of properties for publishing an event to a calendar.
If the calendar service can successfully process the request, it MUST inform the publisher of success. If the publish request did not include an ItemID, the IQ-result SHOULD include an empty <item/> element that specifies the ItemID of the published item.
Note: If the publisher previously published an item with the same ItemID, successfully processing the request means that the service MUST proceed as described in RFC 2446 for the calendaring-specific method used. This usually means that the service MUST overwrite the old calendar entry with a modified entry and then proceed as follows.
The calendar service MUST then send one &MESSAGE; stanza containing a pubsub event notification to each entity that meets the criteria for receiving a notification, as described in section 7.1.2 of XEP-0060. Event notifications MUST be sent specifying the "PUBLISH" method, even if the event notification results from a publishing request that specified a different method.
In addition to the errors already defined for publish requests by XEP-0060, there are several reasons why the request might fail:
These error cases are described more fully in the following sections.
If the namespace of the root payload element submitted in the request does not match the configured namespace for the node (i.e., the 'urn:ietf:params:xml:ns:xcal' namespace) or the payload does not conform to the syntax of the 'urn:ietf:params:xml:ns:xcal' namespace, the service MUST respond with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-payload/>.
If the calendar component submitted in the request does not contain a type of calendar component that is supported in the calendar node (see section Calendar Node Configuration), the service MUST respond with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <item-forbidden/>.
If the calendar component submitted in the request does not obey all restrictions specified in section Calendar Items (e.g., calendar items MUST NOT contain more than one type of calendar component), in section Request (e.g., the request MUST specify an iCalendar "METHOD" property, etc.), and/or those defined for the specified iCalendar method, the service MUST respond with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-payload/>.
If the calendar component submitted in the request does not conform to the configuration of the calendar node where the component will be stored (see section Calendar Node Configuration), the service MUST respond with a &badrequest; error, which SHOULD also include a pubsub-specific error condition. The following rules apply:
A calendar service MUST allow entities to request existing calendar items from a calendar node. The reporting method described in this section is an extension of the pubsub <items/> request (defined in section 6.4 of XEP-0060), but can involve much more complex processing. This is valuable in cases where the calendar service has access to all of the information needed to perform the complex request (such as a query), and where it would require multiple requests for the client to retrieve the information needed to perform the same request.
The <calendar-query/> report performs a search for all calendar items that match a specified filter. The response of this report will contain all the calendar item data specified in the request. In the case of the <calendar-data/>, one can explicitly specify the calendar components and properties that should be returned in the calendar item data that matches the filter.
Support for the <calendar-query/> report is REQUIRED.
The syntax is as follows:
If the calendar service can successfully process the request, it SHOULD return all requested calendar item data, although it MAY truncate the result set if it contains a large number of items.
In addition to the errors already defined for retrieval requests by XEP-0060, there are several reasons why the request might fail:
These error cases are described more fully in the following sections.
If the <filter/> element does not conform to the syntax of the 'urn:ietf:params:xml:ns:caldav' namespace, the service MUST respond with a &badrequest; error. For instance, a <filter/> cannot nest a <comp name='VEVENT'/> element in a <comp name='VTODO'/> element, and a <filter/> cannot nest a <time-range start='...' end='...'/> element in a <prop name='SUMMARY'/> element.
If any <comp-filter/>, <prop-filter/>, or <param-filter/> element used in the <filter/> element in the report request makes a reference to components, properties, or parameters for which queries are not supported by the server (i.e., if the <filter/> element attempts to reference an unsupported component, property, or parameter), the service MUST respond with a &badrequest; error.
If the reporting request does not conform to the configuration of the calendar node being queried (see section Calendar Node Configuration), the service MUST respond with a &badrequest; error. The following rules apply:
If any XML attribute specifying a collation does not specify a collation supported by the calendar service as described in section 7.5 of RFC 4791, the service MUST respond with a &badrequest; error.
The <free-busy-query/> report generates a VFREEBUSY object containing free busy information for all the calendar items targeted by the request and that have the "read-free-busy" or "read" privilege granted to the requesting entity. The reporting method described in this section is an extension of the pubsub <items/> request (defined in section 6.4 of XEP-0060).
Support for the <free-busy-query/> report is REQUIRED.
Only VEVENT objects without a "TRANSP" property or with the "TRANSP" property set to "opaque", and VFREEBUSY components SHOULD be considered in generating the free busy time information.
In the case of VEVENT objects, the free or busy time type ("fbtype" parameter) of the "FREEBUSY" properties in the returned VFREEBUSY object SHOULD be derived from the value of the "TRANSP" and "STATUS" properties; see section 7.10 of RFC 4791.
Duplicate busy time periods with the same "fbtype" parameter value SHOULD NOT be specified in the returned VFREEBUSY component. A calendar service SHOULD coalesce consecutive or overlapping busy time periods of the same type. Busy time periods with different "fbtype" parameter values MAY overlap.
The syntax is as follows:
In the following example, Juliet requests the server to return free busy information on the calendar "ccfc0b59-b9d9-4d0f-ac2f-829e7077640e", between 9:00 A.M. and 5:00 P.M. EST (2:00 P.M. and 10:00 P.M. UTC) on the January 4, 2006.
If the calendar service can successfully process the request, it MUST return the generated VFREEBUSY object. The example indicates two busy time intervals of one hour, one of which is tentative.
There are no errors in addition to those already defined for retrieval requests by XEP-0060.
An "ORGANIZER" MAY include a VALARM calendar component in any VEVENT or VTODO component. A VALARM calendar component is a grouping of component properties that is a reminder or alarm for an event or a to-do. For example, it may be used to define a reminder for a pending event or an overdue to-do.
The following example publishes an event with a VALARM calendar component that specifies an audio alarm that will sound at a precise time and repeat 4 more times at 15 minute intervals:
When an entity wishes to subscribe to a calendar node, it sends a subscription request to the calendar service using the <subscribe/> element described in section 6.1 of XEP-0060. To subscribe to alarm notifications, an entity MAY configure its subscription to have the "&SN;#notify_alarm" configuration option set to "true". The entity MAY subscribe and provide the subscription options in the same stanza (as described in 6.3.7 of XEP-0060), or configure the subscription at any time after subscribing (as described in section 6.3 of XEP-0060).
When an alarm is triggered, the calendar service MUST send one &MESSAGE; stanza containing a alarm notification to each entity that meets the criteria for receiving a alarm notification (typically to each approved subscriber who configured its subscription to have the "calendar#notify_alarm" configuration option set to "true"). Depending on the node configuration, the alarm notification either will or will not contain the payload, as shown below.
If the node is configured to include payloads, the subscribers will receive payloads with the alarm notifications.
If the node is configured to not include payloads, the subscribers will receive alarm notifications only. (If payloads are not included, subscribers may request the calendar item via the protocol defined in the Retrieving Calendar Entries section of this document.)
&TODO;
&TODO;
&TODO;
&TODO;
&TODO;
&TODO;
&TODO;
&TODO;
This document introduces no additional security considerations above or beyond those defined in the documents on which it depends.
This document does not require interaction with &IANA;.
This specification defines the following XML namespaces:
Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.
If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.
&TODO;
&TODO;
The protocol documented by this schema is defined in
XEP-xxxx: http://www.xmpp.org/extensions/xep-xxxx.html
]]>