idnits 2.17.1 draft-daboo-caldav-extensions-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 28, 2011) is 4564 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-08) exists of draft-daboo-webdav-sync-06 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft Apple 4 Intended status: Standards Track October 28, 2011 5 Expires: April 30, 2012 7 Collected Extensions to CalDAV 8 draft-daboo-caldav-extensions-01 10 Abstract 12 This document defines a set of extensions to the CalDAV calendar 13 access protocol. 15 Status of this Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on April 30, 2012. 32 Copyright Notice 34 Copyright (c) 2011 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 51 3. Extended Calendar Query Report . . . . . . . . . . . . . . . . 3 52 3.1. CALDAV:comp-filter XML Element . . . . . . . . . . . . . . 4 53 3.2. CALDAV:prop-filter XML Element . . . . . . . . . . . . . . 5 54 3.3. CALDAV:text-match XML Element . . . . . . . . . . . . . . 5 55 3.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 4. Advertising Supported Calendar Component Sets . . . . . . . . 7 57 4.1. CALDAV:supported-calendar-component-sets Property . . . . 8 58 5. Filtering by Calendar Component Type . . . . . . . . . . . . . 9 59 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 60 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 61 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 62 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 9.1. Normative References . . . . . . . . . . . . . . . . . . . 11 64 9.2. Informative References . . . . . . . . . . . . . . . . . . 11 65 Appendix A. Change History (To be removed by RFC Editor 66 before publication) . . . . . . . . . . . . . . . . . 11 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 69 1. Introduction 71 [RFC4791] defines the CalDAV Calendar Access protocol for accessing 72 calendar data stored on a server. With the popularity of CalDAV 73 increasing, a number of useful extensions have been proposed to 74 improve the protocol. This specification collects several of those 75 extensions into one document for convenience. Each extension defined 76 in this specification can be implemented independently of any of the 77 others. 79 Discussion of this Internet-Draft is taking place on the mailing list 80 . 82 2. Conventions Used in This Document 84 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 86 "OPTIONAL" in this document are to be interpreted as described in 87 [RFC2119]. 89 Other notations used in this memo follow the notations of [RFC4791]. 91 3. Extended Calendar Query Report 93 The CALDAV:calendar-query report defined in Section 7.8 of [RFC4791] 94 allows a client to search calendar data for a match to iCalendar 95 component, property or parameter details. As defined, this option 96 supports querying multiple attributes of the iCalendar data at 97 various "nesting" levels based on the syntactic structure of 98 iCalendar itself. When multiple attributes are queried at the same 99 level, each has to match for the query to be successful - effectively 100 defining a logical "and" operation. This does not allow clients to 101 execute a single query to match different attributes of different 102 component types (e.g., clients cannot search for VEVENTs with a 103 particular time-range, or VTODOs that are not completed). Since 104 there is a need to be able to execute such queries, a logical "or" 105 operation is needed. 107 This specification adds a "test" XML attribute to the CALDAV:comp- 108 filter and CALDAV:prop-filter XML elements that accepts values of 109 "allof" or "anyof" to indicate logical "and" or "or" operations 110 respectively. This copies the behavior defined for CARDDAV: 111 addressbook-query reports defined in Section 10.5 of [RFC6352], with 112 the exception that the default value for the attribute is "allof" to 113 match the current behavior. 115 The text comparison operation in [RFC4791] is a simple "contains" 116 operation, however more sophisticated comparisons are sometimes 117 needed (e.g., 'starts with', 'equals', etc). 119 This specification adds a "match-type" XML attribute to the CALDAV: 120 text-match XML element that accepts values of "equals", "contains", 121 "starts-with", or "ends-with", to indicate the comparison operation 122 to be used. This copies the behavior defined for CARDDAV: 123 addressbook-query reports defined in Section 10.5.4 of [RFC6352]. 125 Sometimes clients want to search all component types for a match 126 (e.g., clients cannot find all calendar object resources that contain 127 a SUMMARY property value matching some text irrespective of the top- 128 level component type). 130 This specification allows the use of a single "*" character in the 131 "name" attribute of "comp-filter" elements to require the server to 132 match any component type. 134 Servers advertise support for this extension by including the token 135 "calendar-query-extended" in the DAV response header to an OPTIONS 136 request on any resource supporting the extended query report. 137 Clients MUST check for the presence of that token before using the 138 "test" or "match-type" XML attributes. 140 This specification extends the [RFC4791] XML syntax for the CALDAV: 141 comp-filter, CALDAV:prop-filter and CALDAV:text-match XML elements as 142 follows. 144 3.1. CALDAV:comp-filter XML Element 146 XML Element: CALDAV:comp-filter 148 Updated Definition: 150 153 155 164 Additional Description: The "test" attribute specifies whether any 165 (logical OR) or all (logical AND) of the is-not-defined, time- 166 range, comp-filter or param-filter tests need to match in order 167 for the overall filter to match. 169 3.2. CALDAV:prop-filter XML Element 171 XML Element: CALDAV:prop-filter 173 Updated Definition: 175 179 181 189 Additional Description: The "test" attribute specifies whether any 190 (logical OR) or all (logical AND) of the is-not-defined, time- 191 range, text-filter or param-filter tests need to match in order 192 for the overall filter to match. 194 3.3. CALDAV:text-match XML Element 196 XML Element: CALDAV:text-match 198 Updated Definition: 200 201 203 208 Additional Description: The "match-type" attribute is used to 209 indicate the type of match operation to use. Possible choices 210 are: 212 "equals" - an exact match to the target string 214 "contains" - a substring match, matching anywhere within the 215 target string 217 "starts-with" - a substring match, matching only at the start 218 of the target string 220 "ends-with" - a substring match, matching only at the end of 221 the target string 223 3.4. Examples 225 In this request, the client is querying for VEVENTs that start on or 226 after a specific date, or VTODOs that are not completed and not 227 cancelled. 229 REPORT /bernard/work/ HTTP/1.1 230 Host: cal.example.com 231 Depth: 1 232 Content-Type: application/xml; charset="utf-8" 233 Content-Length: xxxx 235 236 238 239 240 241 242 243 244 245 246 247 248 249 250 251 CANCELLED 254 255 256 257 258 259 In this request, the client is querying for any component that 260 contains a VALARM sub-component. 262 REPORT /bernard/work/ HTTP/1.1 263 Host: cal.example.com 264 Depth: 1 265 Content-Type: application/xml; charset="utf-8" 266 Content-Length: xxxx 268 269 271 272 273 274 275 276 277 278 279 280 281 283 4. Advertising Supported Calendar Component Sets 285 CalDAV [RFC4791] supports the notion of calendar collections that are 286 restricted to only containing components of a certain type, or set of 287 types. The protocol allows clients to specify the restricted 288 component sets by supplying a CALDAV:supported-calendar-component-set 289 WebDAV property in an MKCALENDAR or extended MKCOL [RFC5689] request 290 that creates a calendar collection. However, servers themselves 291 might need to restrict the allowed sets of components that can be 292 used in any one calendar (e.g., some servers might only support 293 calendar collections containing components of one type). Currently 294 there is no way for a client to determine what the allowed 295 combination of component types is for use with MKCALENDAR or extended 296 MKCOL. 298 This specification adds a new CALDAV:supported-calendar-component- 299 sets WebDAV property for use on calendar home collections. This 300 property enumerates the allowed sets of calendar components that the 301 server will support for use with MKCALENDAR or extended MKCOL 302 requests. Clients SHOULD check for the presence of this property 303 before issuing an MKCALENDAR or extended MKCOL request that includes 304 a CALDAV:supported-calendar-component-set WebDAV property. When the 305 new property is found on a calendar home, clients MUST only use a 306 CALDAV:supported-calendar-component-set is one advertised as being 307 supported. 309 4.1. CALDAV:supported-calendar-component-sets Property 311 Name: supported-calendar-component-sets 313 Namespace: urn:ietf:params:xml:ns:caldav 315 Purpose: Enumerates the sets of component restrictions the server is 316 willing to allow the client to specify in MKCALENDAR or extended 317 MKCOL requests. 319 Protected: This property MUST be protected and SHOULD NOT be 320 returned by a PROPFIND allprop request (as defined in Section 14.2 321 of [RFC4918]). 323 COPY/MOVE behavior: This property value MUST be preserved in COPY 324 and MOVE operations. 326 Description: If servers apply restrictions on the allowed calendar 327 component sets used when creating a calendar, then those servers 328 SHOULD advertise this property on each calendar home collection 329 within which the restrictions apply. In the absence of this 330 property, clients cannot assume anything about whether the server 331 will enforce a set of restrictions or not - in that case clients 332 need to handle the server rejecting certain combinations of 333 restricted component sets. If this property is present, but 334 contains no child XML elements, then clients can assume that the 335 server imposes no restrictions on the combinations of component 336 types it is willing to accept. If present, each CALDAV:supported- 337 calendar-component-set element represents a valid restriction the 338 client can use in an MKCALENDAR or extended MKCOL request when 339 creating a calendar. 341 Definition: 343 345 347 Example: 349 352 353 354 355 356 357 358 360 361 362 363 364 366 367 368 369 371 372 373 374 375 377 5. Filtering by Calendar Component Type 379 Calendar clients are sometimes "scoped" to only utilize one type of 380 main calendar component type (e.g., a scheduling client that only 381 handles "VEVENT" components, or a task manager that only handles 382 "VTODO" components). CalDAV provides a calendar query report that 383 allows clients to find only calendar object resources that contain a 384 specified main component type, which is useful when initially loading 385 the contents of a calendar into a local cache. However, clients also 386 need to keep that cache updated as changes occur on the server. One 387 way to do that is to use the WebDAV sync report 388 [I-D.daboo-webdav-sync], but that report will return changes for all 389 calendar object resources within a calendar collection. Thus 390 "scoped" clients will be forced to load calendar object resources 391 containing component types they do not care about to discover what 392 type they are, or issue additional queries to see whether the changes 393 reported by the sync report are for component types it handles. A 394 better approach would be to have a way for the WebDAV sync report 395 response to include details of the calendar component type for each 396 calendar object resource that it reports as changed. 398 To better "scope" a WebDAV sync report, this specification recommends 399 that servers SHOULD always include a "component=" parameter (as 400 defined in Section 8.1 of [RFC5545]) in the DAV:getcontenttype WebDAV 401 property media-type value reported for calendar object resources. 402 Clients can then request that property be returned in the WebDAV sync 403 report response for each resource, and thus quickly determine which 404 changes are relevant to them based on component type. 406 Example partial WebDAV sync report response with a component type 407 included. 409 410 http://calendar.example.com/cyrusdaboo/calendar.ics 412 413 414 "00003-abcd1" 415 text/calendar;charset=utf-8;component=vevent< 417 /D:getcontenttype> 418 419 HTTP/1.1 200 OK 420 421 423 6. Security Considerations 425 This specification does not introduce any new security concerns 426 beyond those addressed in CalDAV [RFC4791] and iCalendar [RFC5545]. 428 7. IANA Considerations 430 No IANA actions are needed. 432 8. Acknowledgments 434 Thanks to Bernard Desruisseaux, Mike Douglass, Jeffrey Harris, Arnaud 435 Quillaud, and Nick Zitzmann. This specification came about via 436 discussions at the Calendaring and Scheduling Consortium. 438 9. References 439 9.1. Normative References 441 [I-D.daboo-webdav-sync] 442 Daboo, C. and A. Quillaud, "Collection Synchronization for 443 WebDAV", draft-daboo-webdav-sync-06 (work in progress), 444 July 2011. 446 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 447 Requirement Levels", BCP 14, RFC 2119, March 1997. 449 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 450 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 451 March 2007. 453 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 454 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 456 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling 457 Core Object Specification (iCalendar)", RFC 5545, 458 September 2009. 460 [RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring 461 and Versioning (WebDAV)", RFC 5689, September 2009. 463 9.2. Informative References 465 [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed 466 Authoring and Versioning (WebDAV)", RFC 6352, August 2011. 468 Appendix A. Change History (To be removed by RFC Editor before 469 publication) 471 Changes in -01: 473 1. Changed description of COPY/MOVE for supported-calendar- 474 component-sets property 476 2. Removed bogus text in property description. 478 3. Changed supported-calendar-component-sets to use supported- 479 calendar-component-set as a child element. 481 4. Added recommendation to use "component=" parameter in DAV: 482 getcontenttype WebDAV properties on calendar object resources. 484 Author's Address 486 Cyrus Daboo 487 Apple Inc. 488 1 Infinite Loop 489 Cupertino, CA 95014 490 USA 492 Email: cyrus@daboo.name 493 URI: http://www.apple.com/