Abstract
This document defines new protocol features for CalDAV (IETF RFC 4791) to improve the efficiency of synchronizing data changes between a client and server.
Introduction
The CalDAV IETF RFC 4791 protocol is a client/server protocol that supports the exchange of iCalendar IETF RFC 5545 data between a server and clients, as well as supporting scheduling operations on the server (using IETF RFC 6638). To exchange data, clients and servers use a combination of HTTP PUT, GET and REPORT requests. The REPORT requests include CalDAV “multiget” and “time-range” queries, as well as WebDAV-based synchronization IETF RFC 6578. Whilst these have proved adequate to date, there is a need to improve the efficiency of data synchronization to lower network I/O requirements, and thus reduce power consumption requirements on mobile devices (which are now frequently used to manage calendars).
The iCalendar patch [draft-patch] specification defines a way for clients to incrementally update servers using the HTTP PATCH IETF RFC 5789 method and a new iCalendar-based patch format. This allows a client to only send the pieces of an iCalendar object that have changed, rather than send the entire resource. This can significantly reduce the amount of data sent from the client to the server, particularly in enterprise environments where long-lived recurring events, with many attendees, and many recurrence exceptions are common. However, when data changes on the server, clients are still required to download the entire calendar resource, even when only a small change has taken place. Since many users now have multiple devices that are actively synchronizing with a server (e.g., desktop, laptop, mobile phone, tablet, etc) a small change made on one device will result in large data transfers on the others as they synchronize their local caches.
This specification defines new protocol features in CalDAV to support incremental updates to data stored in a client’s cache, by sending calendar patch data from the server to the client. These features are intended to be data format agnostic, and can be used with iCalendar patch, and future patch formats whether they be for existing (e.g. jCal IETF RFC 7265, xCal IETF RFC 6321) or new calendar data formats.
Enhanced Synchronization for Calendaring Extensions to WebDAV (CalDAV)
1. Scope
This document specifies protocol features for CalDAV to improve the efficiency of synchronizing data changes between a client and server.
2. Normative references
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.
IETF RFC 2119, S. BRADNER. Key words for use in RFCs to Indicate Requirement Levels. 1997. RFC Publisher. https://www.rfc-editor.org/info/rfc2119.
IETF RFC 4791, C. DABOO, B. DESRUISSEAUX and L. DUSSEAULT. Calendaring Extensions to WebDAV (CalDAV). 2007. RFC Publisher. https://www.rfc-editor.org/info/rfc4791.
IETF RFC 5234, P. OVERELL. Augmented BNF for Syntax Specifications: ABNF. 2008. RFC Publisher. https://www.rfc-editor.org/info/rfc5234.
IETF RFC 5545, B. DESRUISSEAUX (ed.). Internet Calendaring and Scheduling Core Object Specification (iCalendar). 2009. RFC Publisher. https://www.rfc-editor.org/info/rfc5545.
IETF RFC 5789, L. DUSSEAULT and J. SNELL. PATCH Method for HTTP. 2010. RFC Publisher. https://www.rfc-editor.org/info/rfc5789.
IETF RFC 6321, C. DABOO, M. DOUGLASS and S. LEES. xCal: The XML Format for iCalendar. 2011. RFC Publisher. https://www.rfc-editor.org/info/rfc6321.
IETF RFC 6578, C. DABOO and A. QUILLAUD. Collection Synchronization for Web Distributed Authoring and Versioning (WebDAV). 2012. RFC Publisher. https://www.rfc-editor.org/info/rfc6578.
IETF RFC 6638, C. DABOO and B. DESRUISSEAUX. Scheduling Extensions to CalDAV. 2012. RFC Publisher. https://www.rfc-editor.org/info/rfc6638.
IETF RFC 7230, R. FIELDING and J. RESCHKE (eds.). Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. 2014. RFC Publisher. https://www.rfc-editor.org/info/rfc7230.
IETF RFC 7240, J. SNELL. Prefer Header for HTTP. 2014. RFC Publisher. https://www.rfc-editor.org/info/rfc7240.
IETF RFC 7265, P. KEWISCH, C. DABOO and M. DOUGLASS. jCal: The JSON Format for iCalendar. 2014. RFC Publisher. https://www.rfc-editor.org/info/rfc7265.
3. Terms and definitions
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 IETF RFC 2119.
The notation used in this memo is the ABNF notation of IETF RFC 5234. Any syntax elements shown below that are not explicitly defined in this specification come from HTTP and CalDAV.
When XML element types in the namespaces “DAV:” and “urn:ietf:params:xml:ns:caldav” are referenced in this document outside of the context of an XML fragment, the string “DAV:” and “CALDAV:” will be prefixed to the element type names respectively.
4. Overview
Synchronization of CalDAV data on a client is nowadays typically accomplished using the WebDAV sync REPORT to detect changes to individual calendar object resources in a calendar collection. Those can be retrieved by the WebDAV sync request itself, or a subsequent series of CalDAV multiget requests can be made to retrieve the changed data. WebDAV sync defines a DAV:sync-token property on collections that support synchronization. The value of that property is an opaque token that serves as a “sync anchor” for retrieval of changes on the server. Each client that maintains a local cache of the data stores the last value of DAV:sync-token for a fully synchronized calendar collection, and then presents that token to the server the next time changes need to be fetched. The server then uses that token to determine what has changed since the client last synchronized, and can return those changes. Since the DAV:sync-token is already being used to track changes on a collection level, it can also be used as a “sync anchor” for the retrieval of incremental changes to the resources within that collection.
This specification makes the following changes to CalDAV (with details of each described in subsequent sections):
HTTP requests that expect calendar data to be included in the response (GET and REPORTs which include the CALDAV:calendar-data “property” in the XML body) can include a Prefer request header field IETF RFC 7240 with the “calendar-patch” preference. The client sets the value of the “since” parameter of this preference to a DAV:sync-token value. When such a request is received by the server, if the “since” value represents a valid “sync anchor”, the server MAY use calendar patch documents in the HTTP response. Those documents represent the difference between each calendar resource as it was at the time the client-provided “sync anchor” was in effect, and the current state of the resource.
HTTP multi-status responses that include calendar patch documents MAY use a 304 (Not Modified) status code inside a DAV:propstat element containing a CALDAV:calendar-data element to indicate that there is no difference between the current state of the resource and the state indicated by the “sync anchor”.
5. The “calendar-patch” Preference
The “calendar-patch” preference indicates that the client wishes for the server to use calendar patch documents in the HTTP response rather than entire calendar resources. The value of the “since” parameter, which MUST be the value of a previously returned DAV:sync-token property, provides the “sync anchor” from which the server should generate the patch documents.
ABNF:
calendar-patch = "calendar-patch" OWS ";" OWS "since=" sync-token
sync-token = DQUOTE absolute-URI DQUOTE
6. Changes to GET requests
A client can signal to a server that it is willing and able to receive a calendar patch document rather than an entire calendar resource by including a Prefer header field with the “calendar-patch” preference in a GET request.
If a server receives a “calendar-patch” preference, recognizes the supplied sync-token, and is able to create a patch document for the resource in a format compatible with one of the media types supplied in the Accept IETF RFC 7230 request header field, the server MAY respond to the request with the patch document in lieu of the entire resource.
EXAMPLE
>> Request <<
GET /events/abcd.ics HTTP/1.1
Host: cal.example.com
Prefer: calendar-patch; since="http://example.com/ns/sync/1234"
Accept: text/calendar; component=VPATCH
>> Response <<
HTTP/1.1 200 OK
Date: Sat, 11 Feb 2017 09:32:12 GMT
Content-Type: text/calendar; component=VPATCH; charset="utf-8"
Content-Length: yyyy
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Server//EN
BEGIN:VPATCH
UID:wxyz
DTSTAMP:20170201T000000Z
BEGIN:PATCH
PATCH-TARGET:/VCALENDAR/VEVENT[UID=abcd]
BEGIN:VALARM
UID:hijk
ACTION:DISPLAY
TRIGGER:-PT30M
DESCRIPTION:Time to leave
END:VALARM
END:PATCH
END:VPATCH
END:VCALENDAR
7. Changes to CalDAV REPORT requests
A client fetching the CALDAV:calendar-data “property” in a CALDAV:calendar-query or CALDAV:calendar-multiget REPORT can signal to a server that it is willing and able to receive calendar patch documents rather than entire calendar resources by including a Prefer header field with the “calendar-patch” preference in the REPORT request.
If a server receives a “calendar-patch” preference, recognizes the supplied sync-token, and is able to create patch documents for resources in a format compatible with the “content-type” attribute of the CALDAV:calendar-data element, the server MAY respond to the request with patch documents in lieu of entire resources. If a resource has not changed since the state indicated by the sync-token, the server MAY respond with a 304 (Not Modified) status code in the DAV:propstat element containing the CALDAV:calendar-data element in lieu of an empty calendar patch document.
EXAMPLE
>> Request <<
REPORT /events/work/ HTTP/1.1
Host: cal.example.com
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
Prefer: calendar-patch; since="http://example.com/ns/sync/1234"
<?xml version="1.0" encoding="utf-8" ?>
<C:calendar-multiget xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:prop>
<D:getetag/>
<C:calendar-data content-type="text/calendar; component=VPATCH"/>
</D:prop>
<D:href>/events/work/abcd1.ics</D:href>
<D:href>/events/work/mtg1.ics</D:href>
</C:calendar-multiget>
>> Response <<
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Feb 2017 09:32:12 GMT
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:response>
<D:href>http://cal.example.com/events/work/abcd1.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"fffff-abcd1"</D:getetag>
<C:calendar-data>BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VPATCH
UID:qrst
DTSTAMP:20170201T000000Z
BEGIN:PATCH
PATCH-TARGET:/VCALENDAR/VEVENT[UID=abcd1]
ATTENDEE;PATCH-ACTION=BYVALUE;PARTSTAT=ACCEPTED:
mailto:cyrus@example.com
END:PATCH
END:VPATCH
END:VCALENDAR
</C:calendar-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://cal.example.com/events/work/mtg1.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"fffff-wxyz"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<C:calendar-data/>
</D:prop>
<D:status>HTTP/1.1 304 Not Modified</D:status>
</D:propstat>
</D:response>
</D:multistatus>
8. Changes to WebDAV Sync Collection REPORT requests
A client fetching the CALDAV:calendar-data “property” in a DAV:sync-collection REPORT can signal to a server that it is willing and able to receive calendar patch documents rather than entire calendar resources by including a Prefer header field with the “calendar-patch” preference in the REPORT request. The value of the sync-token specified in the Prefer request header field MUST match that of the DAV:sync-token element in the REPORT body.
If a server receives a “calendar-patch” preference, recognizes the supplied sync-token, and is able to create patch documents for resources in a format compatible with the “content-type” attribute of the CALDAV:calendar-data element, the server MAY respond to the request with patch documents in lieu of entire resources. If a resource has not changed since the state indicated by the sync-token, the server MAY respond with a 304 (Not Modified) status code in the DAV:propstat element containing the CALDAV:calendar-data element in lieu of an empty calendar patch document.
EXAMPLE
>> Request <<
REPORT /events/work/ HTTP/1.1
Host: cal.example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Prefer: calendar-patch; since="http://example.com/ns/sync/1234"
<?xml version="1.0" encoding="utf-8" ?>
<D:sync-collection xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
<D:sync-level>1</D:sync-level>
<D:prop>
<D:getetag/>
<C:calendar-data content-type="text/calendar; component=VPATCH"/>
</D:prop>
</D:sync-collection>
>> Response <<
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Feb 2017 09:32:12 GMT
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:response>
<D:href>http://cal.example.com/events/work/abcd1.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"fffff-abcd1"</D:getetag>
<C:calendar-data>BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VPATCH
UID:qrst
DTSTAMP:20170201T000000Z
BEGIN:PATCH
PATCH-TARGET:/VCALENDAR/VEVENT[UID=abcd1]
ATTENDEE;PATCH-ACTION=BYVALUE;PARTSTAT=ACCEPTED:
mailto:cyrus@example.com
END:PATCH
END:VPATCH
END:VCALENDAR
</C:calendar-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:sync-token>http://example.com/ns/sync/1238</D:sync-token>
</D:multistatus>
9. Security Considerations
Security considerations described in IETF RFC 5545, IETF RFC 5789, and IETF RFC 4791 MUST be adhered to.
10. Privacy Considerations
Privacy considerations described in IETF RFC 5545, IETF RFC 5789, and IETF RFC 4791 MUST be adhered to.
11. IANA Considerations
The following preference is to be added to the HTTP Preferences Registry defined in IETF RFC 7240, Section 5.1.
Preference
calendar-patch
Parameters
since = <sync-token>
Description
The “calendar-patch” preference indicates that the client wishes for the server to use calendar patch documents in the HTTP response rather than entire calendar resources. The value of the “since” parameter provides the anchor point from which the server should generate the patch documents.
Reference
RFCXXXX, Clause 5
Notes
This preference is only intended to be used with CalDAV requests that expect calendar data to be included in the response. Furthermore, the “since” parameter is REQUIRED with this preference.
12. Acknowledgments
Thanks to the following for feedback: Mike Douglass, Bron Gondwana.
This specification originated from work at the Calendaring and Scheduling Consortium, which has helped with the development and testing of implementations.