This document defines new protocol features for CalDAV (
© 2017 The Calendaring and Scheduling Consortium, Inc.
This document is not a CalConnect Standard. It is distributed for review and comment, and is subject to change without notice and may not be referred to as a Standard. Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior written permission. Permission can be requested from the address below.
The Calendaring and Scheduling Consortium, Inc.
4390 Chaffin Lane
McKinleyville
California 95519
United States of America
www.calconnect.org
This document defines new protocol features for CalDAV (
The CalDAV
The iCalendar patch [draft-patch] specification defines a way for clients to incrementally update servers using the HTTP PATCH
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
This document specifies protocol features for CalDAV to improve the efficiency of synchronizing data changes between a client and server.
No terms and definitions are listed in this document.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in
The notation used in this memo is the ABNF notation of
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.
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
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”.
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:
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
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.
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.
Security considerations described in
Privacy considerations described in
The following preference is to be added to the HTTP Preferences Registry defined in
calendar-patch
since = <sync-token>
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.
RFCXXXX,
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.
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.
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
This document defines extensions to the Web Distributed Authoring and Versioning (WebDAV) protocol to specify a standard way of accessing, managing, and sharing calendaring and scheduling information based on the iCalendar format. This document defines the “calendar-access” feature of CalDAV. [STANDARDS-TRACK]
Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]
This document defines the iCalendar data format for representing and exchanging calendaring and scheduling information such as events, to-dos, journal entries, and free/busy information, independent of any particular calendar service or protocol. [STANDARDS-TRACK]
Several applications extending the Hypertext Transfer Protocol (HTTP) require a feature to do partial resource modification. The existing HTTP PUT method only allows a complete replacement of a document. This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource. [STANDARDS-TRACK]
This specification defines “xCal”, an XML format for iCalendar data. [STANDARDS-TRACK]
This specification defines an extension to Web Distributed Authoring and Versioning (WebDAV) that allows efficient synchronization of the contents of a WebDAV collection. [STANDARDS-TRACK]
This document defines extensions to the Calendaring Extensions to WebDAV (CalDAV) “calendar-access” feature to specify a standard way of performing scheduling operations with iCalendar-based calendar components. This document defines the “calendar-auto-schedule” feature of CalDAV. [STANDARDS-TRACK]
The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document provides an overview of HTTP architecture and its associated terminology, defines the “http” and “https” Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.
This specification defines an HTTP header field that can be used by a client to request that certain behaviors be employed by a server while processing a request.
This specification defines “jCal”, a JSON format for iCalendar data. The iCalendar data format is a text format for capturing and exchanging information normally stored within a calendaring and scheduling application, for example, tasks and events. JSON is a lightweight, text-based, language-independent data interchange format commonly used in Internet applications.