The Guide to Internet Calendaring [1] describes the relationship between various internet calendaring specifications like this: "iCalendar [2] is the language used to describe calendar objects. iTIP [3] (Transport-Independent Interoperability Protocol) describes a way to use the iCalendar language to do scheduling. iMIP [4] (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. CalDAV [5] (Calendaring Extensions to WebDAV) is a WebDAV [6] (Web-based Distributed Authoring and Versioning) based mechanism for manipulating internet calendars, and viewing free/busy lists, and via a planned scheduling extension [7], could be used for proposing calendar events as well.
This specification defines calendaring extensions to Publish-Subscribe (XEP-0060) [8] 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 iCalendar in XML Format [9]. 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.
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//ACME/DesktopCalendar//EN
BEGIN:VEVENT
ORGANIZER:xmpp:a@example.com
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
DTSTAMP:19970611T190000Z
SUMMARY;LANGUAGE="en_US":Bastille Day Party
UID:fcd5cb18-93a6-478d-8f71-95cd78e8ebe6
END:VEVENT
END:VCALENDAR
<vcalendar xmlns='urn:ietf:params:xml:ns:xcal'>
<version>2.0</version>
<prodid>-//ACME/DesktopCalendar//EN</prodid>
<vevent>
<organizer>xmpp:a@example.com</organizer>
<dtstart>1997-07-14T17:00:00Z</dtstart>
<dtend>1997-07-15T03:59:59Z</dtend>
<dtstamp>1997-06-11T19:00:00Z</dtstamp>
<summary xml:lang='en-US'>Bastille Day Party</summary>
<uid>fcd5cb18-93a6-478d-8f71-95cd78e8ebe6</uid>
</vevent>
</vcalendar>
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 'urn:xmpp:tmp:calendar:0' feature (see Namespace Versioning regarding the possibility of incrementing the version number) 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.
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 "urn:xmpp:tmp:calendar:0" as a feature in the "disco#info" result. A feature of "urn:xmpp:tmp:calendar:0" (see Namespace Versioning regarding the possibility of incrementing the version number) in the result MUST indicate that the service supports all MUST level requirements in this specification.
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='feature1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='feature1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity category='pubsub' type='service'/>
<feature var='http://jabber.org/protocol/pubsub'/>
<feature var='urn:xmpp:tmp:calendar:0'/>
...
</query>
</iq>
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 "urn:xmpp:tmp:calendar:0" (see Namespace Versioning regarding the possibility of incrementing the version number) 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.
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='meta1'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='princely_musings'/>
</iq>
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='meta1'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='princely_musings'/>
<identity category='pubsub' type='leaf'/>
<feature var='http://jabber.org/protocol/pubsub'/>
<feature var='urn:xmpp:tmp:calendar:0'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#meta-data</value>
</field>
<field var='pubsub#type' label='Payload type'>
<value>urn:ietf:params:xml:ns:xcal</value>
</field>
<field var='pubsub#creator' label='Node creator'>
<value>hamlet@denmark.lit</value>
</field>
<field var='pubsub#creation_date' label='Creation date'>
<value>2003-07-29T22:56Z</value>
</field>
<field var='pubsub#title' label='A short name for the node'>
<value>Princely Musings (Atom)</value>
</field>
<field var='pubsub#description' label='A description of the node'>
<value>Updates for Hamlet's Princely Musings weblog.</value>
</field>
<field var='pubsub#language' label='Default language'>
<value>en</value>
</field>
<field var='pubsub#contact' label='People to contact with questions'>
<value>bard@shakespeare.lit</value>
</field>
<field var='pubsub#owner' label='Node owners'>
<value>hamlet@denmark.lit</value>
</field>
<field var='pubsub#publisher' label='Publishers to this node'>
<value>hamlet@denmark.lit</value>
</field>
<field var='pubsub#num_subscribers' label='Number of subscribers to this node'>
<value>1066</value>
</field>
</x>
</query>
</iq>
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".
<iq type='set'
from='bard@shakespeare.lit/globe'
to='cal.example.com'
id='create3'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<create node='/home/lisa/calendars/events/'/>
<configure>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#node_config</value>
</field>
<field var='pubsub#type'>
<value>urn:ietf:params:xml:ns:xcal</value>
</field>
<field var='pubsub#access_model'>
<value>authorize</value>
</field>
<field var='pubsub#title'>
<value>Lisa's Events</value>
</field>
<field var='pubsub#description'>
<value>Calendar restricted to events.</value>
</field>
<field var='calendar#component_set'>
<value>VEVENT</value>
<value>VFREEBUSY</value>
</fields>
</x>
</configure>
</pubsub>
</iq>
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.
<iq type='result'
from='pubsub.shakespeare.lit'
to='bard@shakespeare.lit/globe'
id='create3'/>
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 <not-allowed/> error.
<iq type='error'
from='hamlet@denmark.lit/elsinore'
to='pubsub.shakespeare.lit'
id='config1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
<configure node='princely_musings'/>
</pubsub>
<error type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
If the requesting entity has insufficient privileges to create new calendar nodes, the service MUST respond with a <forbidden/> error.
<iq type='error'
from='pubsub.shakespeare.lit'
to='hamlet@denmark.lit/elsinore'
id='config1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
<configure node='princely_musings'/>
</pubsub>
<error type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
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 |
| calendar#timezone | text-single | Specifies a time zone on a calendar node. | calendar-timezone |
| calendar#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 |
| calendar#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 |
| calendar#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 |
| calendar#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 |
| calendar#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.
<iq type='set'
from='romeo@montague.net/orchard'
to='calendar.shakespeare.lit'
id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item id='4785a496-9200-43f7-ba32-53c58e03ba37'>
<vcalendar xmlns='urn:ietf:params:xml:ns:xcal'>
<method>PUBLISH</method>
<prodid>-//ACME/DesktopCalendar//EN</prodid>
<version>2.0</version>
<vevent>
<organizer>xmpp:romeo@montague.net</organizer>
<dtstart>1997-07-01T20:00:00Z</dtstart>
<dtstamp>1997-06-11T19:00:00Z</dtstamp>
<summary>ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES</summary>
<uid>4785a496-9200-43f7-ba32-53c58e03ba37</uid>
</vevent>
</vcalendar>
</item>
</publish>
</pubsub>
</iq>
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.
<iq type='result'
from='pubsub.shakespeare.lit'
to='hamlet@denmark.lit/blogbot'
id='publish1'/>
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 <bad-request/> error, which SHOULD also include a pubsub-specific error condition of <invalid-payload/>.
<iq type='error'
from='pubsub.shakespeare.lit'
to='hamlet@denmark.lit/elsinore'
id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
... INVALID PAYLOAD ...
</item>
</publish>
</pubsub>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<invalid-payload xmlns='http://jabber.org/protocol/pubsub#errors'/>
</error>
</iq>
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 <bad-request/> 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 <bad-request/> 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 <bad-request/> 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:
<iq type='get'
from='juliet@capulet.com/balcony'
to='calendaring.shakespeare.lit'
id='items1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<calendar-query xmlns='urn:ietf:params:xml:ns:caldav'>
<filter>
<comp-filter name='VCALENDAR'>
<comp-filter name='VEVENT'>
<time-range start='2006-01-04T00:00:00Z' end='2006-01-05T00:00:00Z'/>
</comp-filter>
</comp-filter>
</filter>
</calendar-query>
</items>
</pubsub>
</iq>
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.
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='items1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='princely_musings'>
<item id='368866411b877c30064a5f62b917cffe'>
... PAYLOAD ...
</item>
<item id='4e30f35051b7b8b42abe083742187228'>
... PAYLOAD ...
</item>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
... PAYLOAD ...
</item>
</items>
</pubsub>
</iq>
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 <bad-request/> 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 <bad-request/> 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 <bad-request/> 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 <bad-request/> 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.
<iq type='get'
from='juliet@capulet.com/balcony'
to='calendaring.shakespeare.lit'
id='items4'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<free-busy-query xmlns='urn:ietf:params:xml:ns:caldav'>
<time-range start='2006-01-04T14:00:00Z' end='2006-01-05T22:00:00Z'/>
</free-busy-query>
</items>
</pubsub>
</iq>
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.
<iq type='result'
from='calendaring.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='items4'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item>
<vfreebusy xmlns='urn:ietf:params:xml:ns:xcal'>
<dtstamp>2005-01-25T09:00:00Z</dtstamp>
<dtstart>2006-01-04T14:00:00Z</dtstart>
<dtend>2006-01-05T22:00:00Z</dtend>
<freebusy fbtype='busy-tentative'>2006-01-04T15:00:00Z PT1H</freebusy>
<freebusy>2006-01-04T19:00:00Z PT1H</freebusy>
</vfreebusy>
</item>
</items>
</pubsub>
</iq>
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:
<iq type='set'
from='romeo@montague.net/orchard'
to='calendar.shakespeare.lit'
id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item id='4785a496-9200-43f7-ba32-53c58e03ba37'>
<vcalendar xmlns='urn:ietf:params:xml:ns:xcal'>
<method>PUBLISH</method>
<prodid>-//ACME/DesktopCalendar//EN</prodid>
<version>2.0</version>
<vevent>
<organizer>xmpp:romeo@montague.net</organizer>
<dtstart>1997-07-01T20:00:00Z</dtstart>
<dtstamp>1997-06-11T19:00:00Z</dtstamp>
<summary>ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES</summary>
<uid>4785a496-9200-43f7-ba32-53c58e03ba37</uid>
<valarm>
<trigger value='date-time'>1997-03-17T13:30:00Z</trigger>
<repeat>4</repeat>
<duration>PT15M</duration>
<action>audio</action>
<attach fmttype='audio/basic'>ftp://host.com/pub/sounds/bell-01.aud</attach>
</valarm>
</vevent>
</vcalendar>
</item>
</publish>
</pubsub>
</iq>
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 "calendar#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).
<iq type='set'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='sub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='princely_musings' jid='francisco@denmark.lit'/>
<options>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
</field>
<field var='pubsub#deliver'><value>1</value></field>
<field var='pubsub#digest'><value>0</value></field>
<field var='pubsub#include_body'><value>false</value></field>
<field var='calendar#notify_alarm'><value>true</value></field>
</x>
</options>
</pubsub>
</iq>
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.
<message from='calendar.shakespeare.lit'
to='romeo@montague.net/orchard'
id='alarm1'>
<alarm xmlns='xmpp:tmp:calendar:0'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item id='4785a496-9200-43f7-ba32-53c58e03ba37'>
<vcalendar xmlns='urn:ietf:params:xml:ns:xcal'>
<prodid>-//ACME/DesktopCalendar//EN</prodid>
<version>2.0</version>
<vevent>
<organizer>xmpp:romeo@montague.net</organizer>
<dtstart>1997-07-01T20:00:00Z</dtstart>
<dtstamp>1997-06-11T19:00:00Z</dtstamp>
<summary>ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES</summary>
<uid>4785a496-9200-43f7-ba32-53c58e03ba37</uid>
<valarm>
<trigger value='date-time'>1997-03-17T13:30:00Z</trigger>
<repeat>4</repeat>
<duration>PT15M</duration>
<action>audio</action>
<attach fmttype='audio/basic'>ftp://host.com/pub/sounds/bell-01.aud</attach>
</valarm>
</vevent>
</vcalendar>
</item>
</items>
</alarm>
</message>
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.)
<message from='calendar.shakespeare.lit'
to='romeo@montague.net/orchard'
id='alarm2'>
<alarm xmlns='xmpp:tmp:calendar:0'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item id='4785a496-9200-43f7-ba32-53c58e03ba37' />
</items>
</alarm>
</message>
## 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 the Internet Assigned Numbers Authority (IANA) [10].
This specification defines the following XML namespaces:
Upon advancement of this specification from a status of Experimental to a status of Draft, the XMPP Registrar [11] shall add the foregoing namespaces to the registry located at <https://xmpp.org/registrar/namespaces.html>, as described in Section 4 of XMPP Registrar Function (XEP-0053) [12].
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. ##
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='xmpp:tmp:calendar:0'
xmlns='xmpp:tmp:calendar:0'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
XEP-xxxx: http://www.xmpp.org/extensions/xep-xxxx.html
</xs:documentation>
</xs:annotation>
<xs:element name='alarm'>
<xs:complexType>
<xs:choice minOccurs='0'>
<xs:element ref='items'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='items'>
<xs:complexType>
<xs:choice>
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
<xs:attribute name='node' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:choice minOccurs='0'>
<xs:any namespace='##other'/>
</xs:choice>
<xs:attribute name='id' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
</xs:schema>
This document in other formats: XML PDF
This XMPP Extension Protocol is copyright © 1999 – 2024 by the XMPP Standards Foundation (XSF).
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.
## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).
The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.
Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.
Given that this XMPP Extension Protocol normatively references IETF technologies, discussion on the <xsf-ietf@xmpp.org> list might also be appropriate.
Errata can be sent to <editor@xmpp.org>.
The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. RFC 3283: Guide to Internet Calendaring <http://tools.ietf.org/html/rfc3283>.
2. RFC 2445: Internet Calendaring and Scheduling Core Object Specification (iCalendar) <http://tools.ietf.org/html/rfc2445>.
3. RFC 2446: iCalendar Transport-Independent Interoperability Protocol (iTIP) <http://tools.ietf.org/html/rfc2446>.
4. RFC 2447: iCalendar Message-Based Interoperability Protocol (iMIP) <http://tools.ietf.org/html/rfc2447>.
5. RFC 4791: Calendaring Extensions to WebDAV (CalDAV) <http://tools.ietf.org/html/rfc4791>.
6. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) <http://tools.ietf.org/html/rfc4918>.
7. CalDAV Scheduling Extensions to WebDAV <http://tools.ietf.org/html/draft-desruisseaux-caldav-sched-04>.
8. XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>.
9. iCalendar in XML Format (xCal-Basic) <http://tools.ietf.org/html/draft-royer-calsch-xcal-03>.
10. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
11. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <https://xmpp.org/registrar/>.
12. XEP-0053: XMPP Registrar Function <https://xmpp.org/extensions/xep-0053.html>.
Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/
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.
@report{hartke2007calendar,
title = {Calendaring Extensions to Publish-Subscribe},
author = {Hartke, Klaus},
type = {XEP},
number = {xxxx},
version = {0.0.3.1},
institution = {XMPP Standards Foundation},
url = {https://xmpp.org/extensions/xep-xxxx.html},
date = {2007-12-08/2009-02-14},
}END