idnits 2.17.1 draft-ietf-vcarddav-carddav-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 9, 2009) is 5520 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 (-22) exists of draft-ietf-vcarddav-vcardrev-06 == Outdated reference: A later version (-06) exists of draft-ietf-vcarddav-webdav-mkcol-03 ** Obsolete normative reference: RFC 2426 (Obsoleted by RFC 6350) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). 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 March 9, 2009 5 Expires: September 10, 2009 7 vCard Extensions to WebDAV (CardDAV) 8 draft-ietf-vcarddav-carddav-06 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. This document may contain material 14 from IETF Documents or IETF Contributions published or made publicly 15 available before November 10, 2008. The person(s) controlling the 16 copyright in some of this material may not have granted the IETF 17 Trust the right to allow modifications of such material outside the 18 IETF Standards Process. Without obtaining an adequate license from 19 the person(s) controlling the copyright in such materials, this 20 document may not be modified outside the IETF Standards Process, and 21 derivative works of it may not be created outside the IETF Standards 22 Process, except to format it for publication as an RFC or to 23 translate it into languages other than English. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt. 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 This Internet-Draft will expire on September 10, 2009. 43 Copyright Notice 45 Copyright (c) 2009 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents in effect on the date of 50 publication of this document (http://trustee.ietf.org/license-info). 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. 54 Abstract 56 This document defines extensions to the Web Distributed Authoring and 57 Versioning (WebDAV) protocol to specify a standard way of accessing, 58 managing, and sharing contact information based on the vCard format. 60 Table of Contents 62 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 63 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 65 2.2. XML Namespaces and Processing . . . . . . . . . . . . . . 5 66 3. Requirements Overview . . . . . . . . . . . . . . . . . . . . 6 67 4. Address Book Data Model . . . . . . . . . . . . . . . . . . . 7 68 4.1. Address Book Server . . . . . . . . . . . . . . . . . . . 7 69 5. Address Book Resources . . . . . . . . . . . . . . . . . . . . 7 70 5.1. Address Object Resources . . . . . . . . . . . . . . . . . 7 71 5.2. Address Book Collections . . . . . . . . . . . . . . . . . 8 72 6. Address Book Feature . . . . . . . . . . . . . . . . . . . . . 9 73 6.1. Address Book Support . . . . . . . . . . . . . . . . . . . 9 74 6.1.1. Example: Using OPTIONS for the Discovery of 75 Support for CardDAV . . . . . . . . . . . . . . . . . 9 76 6.2. Address Book Properties . . . . . . . . . . . . . . . . . 9 77 6.2.1. CARDDAV:addressbook-description Property . . . . . . . 10 78 6.2.2. CARDDAV:supported-address-data Property . . . . . . . 10 79 6.2.3. CARDDAV:max-resource-size Property . . . . . . . . . . 11 80 6.3. Creating Resources . . . . . . . . . . . . . . . . . . . . 12 81 6.3.1. Extended MKCOL Method . . . . . . . . . . . . . . . . 12 82 6.3.1.1. Example - Successful MKCOL request . . . . . . . . 13 83 6.3.2. Creating Address Object Resources . . . . . . . . . . 14 84 6.3.2.1. Additional Preconditions for PUT, COPY and MOVE . 15 85 6.3.2.2. Non-Standard vCard Properties, and Parameters . . 16 86 6.3.2.3. Address Object Resource Entity Tag . . . . . . . . 17 87 7. Address Book Access Control . . . . . . . . . . . . . . . . . 17 88 7.1. Additional Principal Properties . . . . . . . . . . . . . 17 89 7.1.1. CARDDAV:addressbook-home-set Property . . . . . . . . 17 90 7.1.2. CARDDAV:principal-address Property . . . . . . . . . . 18 91 8. Address Book Reports . . . . . . . . . . . . . . . . . . . . . 19 92 8.1. REPORT Method . . . . . . . . . . . . . . . . . . . . . . 19 93 8.2. Ordinary Collections . . . . . . . . . . . . . . . . . . . 20 94 8.3. Searching Text: Collations . . . . . . . . . . . . . . . . 20 95 8.3.1. CARDDAV:supported-collation-set Property . . . . . . . 21 97 8.4. Partial Retrieval . . . . . . . . . . . . . . . . . . . . 22 98 8.5. Non-standard Properties and Parameters . . . . . . . . . . 22 99 8.6. CARDDAV:addressbook-query Report . . . . . . . . . . . . . 22 100 8.6.1. Limiting Results . . . . . . . . . . . . . . . . . . . 24 101 8.6.2. Truncation of Results . . . . . . . . . . . . . . . . 24 102 8.6.3. Example: Partial Retrieval of vCards Matching 103 NICKNAME . . . . . . . . . . . . . . . . . . . . . . . 24 104 8.6.4. Example: Partial Retrieval of vCards Matching a 105 Full Name or Email Address . . . . . . . . . . . . . . 26 106 8.6.5. Example: Truncated Results . . . . . . . . . . . . . . 29 107 8.7. CARDDAV:addressbook-multiget Report . . . . . . . . . . . 30 108 8.7.1. Example: CARDDAV:addressbook-multiget Report . . . . . 32 109 9. Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . 33 110 9.1. Restrict the Properties Returned . . . . . . . . . . . . . 33 111 9.2. Use of Locking . . . . . . . . . . . . . . . . . . . . . . 34 112 9.3. Client Configuration . . . . . . . . . . . . . . . . . . . 34 113 9.4. Finding Other Users' Address Books . . . . . . . . . . . . 35 114 10. XML Element Definitions . . . . . . . . . . . . . . . . . . . 35 115 10.1. CARDDAV:addressbook XML Element . . . . . . . . . . . . . 35 116 10.2. CARDDAV:supported-collation XML Element . . . . . . . . . 36 117 10.3. CARDDAV:addressbook-query XML Element . . . . . . . . . . 36 118 10.4. CARDDAV:address-data XML Element . . . . . . . . . . . . . 36 119 10.4.1. CARDDAV:allprop XML Element . . . . . . . . . . . . . 38 120 10.4.2. CARDDAV:prop XML Element . . . . . . . . . . . . . . . 39 121 10.5. CARDDAV:filter XML Element . . . . . . . . . . . . . . . . 39 122 10.5.1. CARDDAV:prop-filter XML Element . . . . . . . . . . . 40 123 10.5.2. CARDDAV:param-filter XML Element . . . . . . . . . . . 41 124 10.5.3. CARDDAV:is-not-defined XML Element . . . . . . . . . . 42 125 10.5.4. CARDDAV:text-match XML Element . . . . . . . . . . . . 42 126 10.6. CARDDAV:limit XML Element . . . . . . . . . . . . . . . . 43 127 10.6.1. CARDDAV:nresults XML Element . . . . . . . . . . . . . 44 128 10.7. CARDDAV:addressbook-multiget XML Element . . . . . . . . . 44 129 11. Service Discovery via SRV Records . . . . . . . . . . . . . . 44 130 12. Internationalization Considerations . . . . . . . . . . . . . 45 131 13. Security Considerations . . . . . . . . . . . . . . . . . . . 45 132 14. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 46 133 14.1. Namespace Registration . . . . . . . . . . . . . . . . . . 46 134 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46 135 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 46 136 16.1. Normative References . . . . . . . . . . . . . . . . . . . 46 137 16.2. Informative References . . . . . . . . . . . . . . . . . . 48 138 Appendix A. Change History (to be removed prior to 139 publication as an RFC) . . . . . . . . . . . . . . . 48 140 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 51 142 1. Introduction and Overview 144 Address books containing contact information are a key component of 145 personal information management tools, such as email, calendaring and 146 scheduling, and instant messaging clients. To date several protocols 147 have been used for remote access to contact data, including 148 Lightweight Directory Access Protocol LDAP [RFC4511], Internet 149 Message Support Protocol IMSP [IMSP] and Application Configuration 150 Access Protocol ACAP [RFC2244], together with SyncML used for 151 synchronization of such data. 153 WebDAV [RFC4918] offers a number of advantages as a framework or 154 basis for address book access and management. Most of these 155 advantages boil down to a significant reduction in design costs, 156 implementation costs, interoperability test costs and deployment 157 costs. 159 The key features of address book support with WebDAV are: 161 1. Ability to use multiple address books with hierarchical layout. 163 2. Ability to control access to individual address books and address 164 entries. 166 3. Principal namespace can be used to enumerate and find other users 167 on the system. 169 4. Server-side searching of address data, avoiding the need for 170 clients to download an entire address book in order to do a quick 171 address 'expansion' operation. 173 5. Well-defined internationalization support through standard HTTP. 175 6. Use of vCards for well defined address schema to enhance client 176 interoperability. 178 7. Many limited clients (e.g. mobile devices) contain an HTTP stack 179 which makes implementing WebDAV much easier than other protocols. 181 The key disadvantages of address book support in WebDAV are: 183 1. Lack of change notification. Many of the alternative protocols 184 also lack this ability. However, an extension for push 185 notifications could easily be developed. 187 2. Stateless nature of protocol can result in more data being sent 188 with each transaction to maintain per-user session across 189 requests. 191 vCard [RFC2426] is a MIME directory profile aimed at encapsulating 192 personal addressing and contact information about people. The 193 specification of vCard was originally done by the Versit consortium, 194 with a subsequent 3.0 version standardized by the IETF [RFC2426]. 195 vCard is in wide spread use in email clients and mobile devices as a 196 means of encapsulating address information for transport via email, 197 or for import/export and synchronization operations. 199 An update to vCard is currently being developed 200 [I-D.ietf-vcarddav-vcardrev] and is compatible with this 201 specification. 203 2. Conventions 205 2.1. Notational Conventions 207 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 208 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 209 document are to be interpreted as described in [RFC2119]. 211 The term "protected" is used in the Conformance field of property 212 definitions as defined in Section 15 of [RFC4918]. 214 When XML element types in the namespaces "DAV:" and 215 "urn:ietf:params:xml:ns:carddav" are referenced in this document 216 outside of the context of an XML fragment, the string "DAV:" and 217 "CARDDAV:" will be prefixed to the element type names, respectively. 219 2.2. XML Namespaces and Processing 221 Definitions of XML elements in this document use XML element type 222 declarations (as found in XML Document Type Declarations), described 223 in Section 3.2 of [W3C.REC-xml-20060816]. 225 The namespace "urn:ietf:params:xml:ns:carddav" is reserved for the 226 XML elements defined in this specification, its revisions, and 227 related CardDAV specifications. XML elements defined by individual 228 implementations MUST NOT use the "urn:ietf:params:xml:ns:carddav" 229 namespace, and instead should use a namespace that they control. 231 The XML declarations used in this document do not include namespace 232 information. Thus, implementers must not use these declarations as 233 the only way to create valid CardDAV properties or to validate 234 CardDAV XML element type. Some of the declarations refer to XML 235 elements defined by WebDAV [RFC4918] which use the "DAV:" namespace. 236 Wherever such XML elements appear, they are explicitly prefixed with 237 "DAV:" to avoid confusion. 239 Also note that some CardDAV XML element names are identical to WebDAV 240 XML element names, though their namespace differs. Care must be 241 taken not to confuse the two sets of names. 243 Processing of XML by CardDAV clients and servers MUST follow the 244 rules described in Section 17 of [RFC4918]. 246 3. Requirements Overview 248 This section lists what functionality is required of a CardDAV 249 server. To advertise support for CardDAV, a server: 251 o MUST support vCard [RFC2426] as a media type for the address 252 object resource format; 254 o MUST support WebDAV Class 3 [RFC4918]; 256 o MUST support WebDAV ACL [RFC3744]; 258 o MUST support secure transport as defined in [RFC2818] using TLS 259 [RFC5246]; 261 o MUST support ETags [RFC2616] with additional requirements 262 specified in Section 6.3.2.3 of this document; 264 o MUST support all address book REPORTs defined in Section 8 of this 265 document; and 267 o MUST advertise support on all addressbook collections and address 268 object resources for the addressbook reports in the DAV:supported- 269 report-set property, as defined in Versioning Extensions to WebDAV 270 [RFC3253]. 272 In addition, a server: 274 o SHOULD support the extended MKCOL method 275 [I-D.ietf-vcarddav-webdav-mkcol] to create address book 276 collections as defined in Section 6.3.1 of this document. 278 o SHOULD support the DAV:current-user-principal-URL property as 279 defined in [RFC5397] to give clients a fast way to locate user 280 principals. 282 4. Address Book Data Model 284 As a brief overview, a CardDAV address book is modeled as a WebDAV 285 collection with a well defined structure; each of these address book 286 collections contain a number of resources representing address 287 objects as their direct child resources. Each resource representing 288 an address object is called an "address object resource". Each 289 address object resource and each address book collection can be 290 individually locked and have individual WebDAV properties. 291 Requirements derived from this model are provided in Section 5.1 and 292 Section 5.2. 294 4.1. Address Book Server 296 A CardDAV server is an address-aware engine combined with a WebDAV 297 server. The server may include address data in some parts of its URL 298 namespace, and non-address data in other parts. 300 A WebDAV server can advertise itself as a CardDAV server if it 301 supports the functionality defined in this specification at any point 302 within the root of its repository. That might mean that address data 303 is spread throughout the repository and mixed with non-address data 304 in nearby collections (e.g. address data may be found in /lisa/ 305 addressbook/ as well as in /bernard/addressbook/, and non-address 306 data in /lisa/calendars/). Or, it might mean that address data can 307 be found only in certain sections of the repository (e.g. 308 /addressbooks/user/). Address book features are only required in the 309 repository sections that are or contain address objects. So a 310 repository confining address data to the /carddav/ collection would 311 only need to support the CardDAV required features within that 312 collection. 314 The CardDAV server is the canonical location for address data and 315 state information. Clients may submit requests to change data or 316 download data. Clients may store address objects offline and attempt 317 to synchronize at a later time. However, clients MUST be prepared 318 for address data on the server to change between the time of last 319 synchronization and when attempting an update, as address book 320 collections may be shared and accessible via multiple clients. 321 Entity tags and other features help this work. 323 5. Address Book Resources 325 5.1. Address Object Resources 327 This specification uses vCard as the default format for address or 328 contact information being stored on the server. However, this 329 specification does allow other formats for address data provided that 330 the server advertises support for those additional formats as 331 described below. The requirements in this section pertain to vCard 332 address data, or formats that follow the semantics of vCard data. 334 Address object resources contained in address book collections MUST 335 contain a single vCard component only. 337 vCard components in an address book collection MUST have a UID 338 property value that MUST be unique in the scope of the address book 339 collection in which it is contained. 341 5.2. Address Book Collections 343 Address book collections appear to clients as a WebDAV collection 344 resource, identified by a URL. An address book collection MUST 345 report the DAV:collection and CARDDAV:addressbook XML elements in the 346 value of the DAV:resourcetype property. The element type declaration 347 for CARDDAV:addressbook is: 349 351 An address book collection can be created through provisioning (e.g., 352 automatically created when a user's account is provisioned), or it 353 can be created with the extended MKCOL method (see Section 6.3.1). 354 This can be used by a user to create additional address books (e.g., 355 "soccer team members") or for users to share an address book (e.g., 356 "sales team contacts"). Note however that this document doesn't 357 define what extra address book collections are for. Users must rely 358 on non-standard cues to find out what an address book collection is 359 for, or use the CARDDAV:addressbook-description property defined in 360 Section 6.2.1 to provide such a cue. 362 The following restrictions are applied to the resources within an 363 address book collection: 365 a. Address book collections MUST only contain address object 366 resources and collections that are not address book collections. 367 i.e., the only "top-level" non-collection resources allowed in an 368 address book collection are address object resources. This 369 ensures that address book clients do not have to deal with non- 370 address data in an address book collection, though they do have 371 to distinguish between address object resources and collections 372 when using standard WebDAV techniques to examine the contents of 373 a collection. 375 b. Collections contained in address book collections MUST NOT 376 contain address book collections at any depth. i.e., "nesting" of 377 address book collections within other address book collections at 378 any depth is not allowed. This specification does not define how 379 collections contained in an address book collection are used or 380 how they relate to any address object resources contained in the 381 address book collection. 383 Multiple address book collections MAY be children of the same 384 collection. 386 6. Address Book Feature 388 6.1. Address Book Support 390 A server supporting the features described in this document, MUST 391 include "addressbook" as a field in the DAV response header from an 392 OPTIONS request on any resource that supports any address book 393 properties, reports, or methods. A value of "addressbook" in the DAV 394 response header MUST indicate that the server supports all MUST level 395 requirements and REQUIRED features specified in this document. 397 6.1.1. Example: Using OPTIONS for the Discovery of Support for CardDAV 399 >> Request << 401 OPTIONS /addressbooks/users/ HTTP/1.1 402 Host: addressbook.example.com 404 >> Response << 406 HTTP/1.1 200 OK 407 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE 408 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL 409 DAV: 1, 2, 3, access-control, addressbook 410 DAV: extended-mkcol 411 Date: Sat, 11 Nov 2006 09:32:12 GMT 412 Content-Length: 0 414 In this example, the OPTIONS response indicates that the server 415 supports CardDAV in this namespace, therefore the '/addressbooks/ 416 users/' collection may be used as a parent for address book 417 collections as the extended MKCOL method is available, and as a 418 possible target for REPORT requests for address book reports. 420 6.2. Address Book Properties 421 6.2.1. CARDDAV:addressbook-description Property 423 Name: addressbook-description 425 Namespace: urn:ietf:params:xml:ns:carddav 427 Purpose: Provides a human-readable description of the address book 428 collection. 430 Value: Any text. 432 Protected: SHOULD NOT be protected so that users can specify a 433 description. 435 COPY/MOVE behavior: This property value SHOULD be preserved in COPY 436 and MOVE operations. 438 allprop behavior: SHOULD be returned by a PROPFIND DAV:allprop 439 request. 441 Description: This property contains a description of the address 442 book collection that is suitable for presentation to a user. 444 Definition: 446 447 449 Example: 451 Adresses de Oliver Daboo 455 6.2.2. CARDDAV:supported-address-data Property 457 Name: supported-address-data 459 Namespace: urn:ietf:params:xml:ns:carddav 461 Purpose: Specifies what media types are allowed for address object 462 resources in an address book collection. 464 Protected: MUST be protected as it indicates the level of support 465 provided by the server. 467 COPY/MOVE behavior: This property value MUST be preserved in COPY 468 and MOVE operations. 470 allprop behavior: SHOULD be returned by a PROPFIND DAV:allprop 471 request. 473 Description: The CARDDAV:supported-address-data property is used to 474 specify the media type supported for the address object resources 475 contained in a given address book collection (e.g., vCard version 476 3.0). Any attempt by the client to store address object resources 477 with a media type not listed in this property MUST result in an 478 error, with the CARDDAV:supported-address-data precondition 479 (Section 6.3.2.1) being violated. In the absence of this property 480 the server MUST only accept data with the media type "text/vcard" 481 and vCard version 3.0, and clients can assume that. 483 Definition: 485 487 Example: 489 491 492 494 6.2.3. CARDDAV:max-resource-size Property 496 Name: max-resource-size 498 Namespace: urn:ietf:params:xml:ns:carddav 500 Purpose: Provides a numeric value indicating the maximum size of a 501 resource in octets that the server is willing to accept when an 502 address object resource is stored in an address book collection. 504 Value: Any text representing a numeric value. 506 Protected: MUST be protected as it indicates limits provided by the 507 server. 509 COPY/MOVE behavior: This property value MUST be preserved in COPY 510 and MOVE operations. 512 allprop behavior: SHOULD be returned by a PROPFIND DAV:allprop 513 request. 515 Description: The CARDDAV:max-resource-size is used to specify a 516 numeric value that represents the maximum size in octets that the 517 server is willing to accept when an address object resource is 518 stored in an address book collection. Any attempt to store an 519 address book object resource exceeding this size MUST result in an 520 error, with the CARDDAV:max-resource-size precondition 521 (Section 6.3.2.1) being violated. In the absence of this property 522 the client can assume that the server will allow storing a 523 resource of any reasonable size. 525 Definition: 527 528 530 Example: 532 102400 535 6.3. Creating Resources 537 Address book collections and address object resources may be created 538 by either a CardDAV client or by the CardDAV server. This 539 specification defines restrictions and a data model that both clients 540 and servers MUST adhere to when manipulating such address data. 542 6.3.1. Extended MKCOL Method 544 An HTTP request using the extended MKCOL method 545 [I-D.ietf-vcarddav-webdav-mkcol] can be used to create a new address 546 book collection resource. A server MAY restrict address book 547 collection creation to particular collections. 549 To create an address book, the client sends an extended MKCOL request 550 to the server and in the body of the request sets the DAV: 551 resourcetype property to the resource type for an address book 552 collection as defined in Section 5.2. 554 Support for creating address books on the server is only RECOMMENDED 555 and not REQUIRED because some address book stores only support one 556 address book per user (or principal), and those are typically pre- 557 created for each account. However, servers and clients are strongly 558 encouraged to support address book creation whenever possible to 559 allow users to create multiple address book collections to help 560 organize their data better. 562 Clients SHOULD use the DAV:displayname property for a human-readable 563 name of the address book. Clients can either specify the value of 564 the DAV:displayname property in the request body of the extended 565 MKCOL request, or alternatively issue a PROPPATCH request to change 566 the DAV:displayname property to the appropriate value immediately 567 after using the extended MKCOL request. Clients SHOULD NOT set the 568 DAV:displayname property to be the same as any other address book 569 collection at the same URI "level". When displaying address book 570 collections to users, clients SHOULD check the DAV:displayname 571 property and use that value as the name of the address book. In the 572 event that the DAV:displayname property is not set, the client MAY 573 use the last part of the address book collection URI as the name, 574 however that path segment may be "opaque" and not represent any 575 meaningful human-readable text. 577 6.3.1.1. Example - Successful MKCOL request 579 This example creates an address book collection called /home/lisa/ 580 addressbook/ on the server addressbook.example.com with specific 581 values for the properties DAV:resourcetype, DAV:displayname and 582 CARDDAV:addressbook-description. 584 >> Request << 586 MKCOL /home/lisa/addressbook/ HTTP/1.1 587 Host: addressbook.example.com 588 Content-Type: text/xml; charset="utf-8" 589 Content-Length: xxx 591 592 594 595 596 597 598 599 600 Lisa's Contacts 601 My primary address book. 603 604 605 606 >> Response << 608 HTTP/1.1 201 Created 609 Cache-Control: no-cache 610 Date: Sat, 11 Nov 2006 09:32:12 GMT 611 Content-Type: application/xml; charset="utf-8" 612 Content-Length: xxxx 614 615 617 618 619 620 621 622 623 HTTP/1.1 200 OK 624 625 627 6.3.2. Creating Address Object Resources 629 Clients populate address book collections with address object 630 resources. The URL for each address object resource is entirely 631 arbitrary, and does not need to bear a specific relationship (but 632 might) to the address object resource's vCard properties or other 633 metadata. New address object resources MUST be created with a PUT 634 request targeted at an unmapped URI. A PUT request targeted at a 635 mapped URI updates an existing address object resource. 637 When servers create new resources, it's not hard for the server to 638 choose a unique URL. It's slightly tougher for clients, because a 639 client might not want to examine all resources in the collection, and 640 might not want to lock the entire collection to ensure that a new one 641 isn't created with a name collision. However, there is an HTTP 642 feature to mitigate this. If the client intends to create a new 643 address resource the client SHOULD use the HTTP header "If-None- 644 Match: *" on the PUT request. The Request-URI on the PUT request 645 MUST include the target collection, where the resource is to be 646 created, plus the name of the resource in the last path segment. The 647 "If-None-Match" header ensures that the client will not inadvertently 648 overwrite an existing resource even, if the last path segment turned 649 out to already be used. 651 >> Request << 653 PUT /lisa/addressbook/newvcard.vcf HTTP/1.1 654 If-None-Match: * 655 Host: addressbook.example.com 656 Content-Type: text/vcard 657 Content-Length: xxx 659 BEGIN:VCARD 660 VERSION:3.0 661 FN:Cyrus Daboo 662 N:Daboo;Cyrus 663 ADR;TYPE=POSTAL:;2822 Email HQ;Suite 2821;RFCVille;PA;15213;USA 664 EMAIL;TYPE=INTERNET,PREF:cyrus@example.com 665 NICKNAME:me 666 NOTE:Example VCard. 667 ORG:Self Employed 668 TEL;TYPE=WORK,VOICE:412 605 0499 669 TEL;TYPE=FAX:412 605 0705 670 URL:http://www.example.com 671 UID:1234-5678-9000-1 672 END:VCARD 674 >> Response << 676 HTTP/1.1 201 Created 677 Date: Thu, 02 Sep 2004 16:53:32 GMT 678 Content-Length: 0 679 ETag: "123456789-000-111" 681 The request to change an existing address object resource is the 682 same, but with a specific ETag in the "If-Match" header, rather than 683 the "If-None-Match" header. 685 File names for vCards are commonly suffixed by ".vcf", and clients 686 may choose to use the same convention for URLs. 688 6.3.2.1. Additional Preconditions for PUT, COPY and MOVE 690 This specification creates additional Preconditions for PUT, COPY and 691 MOVE methods. These preconditions apply: 693 o When a PUT operation of an address object resource into an address 694 book collection occurs. 696 o When a COPY or MOVE operation of an address object resource into 697 an address book collection occurs. 699 The new preconditions are: 701 (CARDDAV:supported-address-data): The resource submitted in the 702 PUT request, or targeted by a COPY or MOVE request MUST be a 703 supported media type (i.e., vCard) for address object resources; 705 (CARDDAV:valid-address-data): The resource submitted in the PUT 706 request, or targeted by a COPY or MOVE request MUST be valid data 707 for the media type being specified (i.e., MUST contain valid vCard 708 data); 710 (CARDDAV:no-uid-conflict): The resource submitted in the PUT 711 request, or targeted by a COPY or MOVE request MUST NOT specify a 712 vCard UID property value already in use in the targeted address 713 book collection or overwrite an existing address object resource 714 with one that has a different UID property value. Servers SHOULD 715 report the URL of the resource that is already making use of the 716 same UID property value in the DAV:href element; 718 720 (CARDDAV:addressbook-collection-location-ok): In a COPY or MOVE 721 request, when the Request-URI is an address book collection, the 722 URI targeted by the Destination HTTP Request header MUST identify 723 a location where an address book collection can be created; 725 (CARDDAV:max-resource-size): The resource submitted in the PUT 726 request, or targeted by a COPY or MOVE request MUST have an octet 727 size less than or equal to the value of the CARDDAV:max-resource- 728 size property value (Section 6.2.3) on the address book collection 729 where the resource will be stored; 731 6.3.2.2. Non-Standard vCard Properties, and Parameters 733 vCard provides a "standard mechanism for doing non-standard things". 734 This extension support allows implementers to make use of non- 735 standard properties and parameters whose names are prefixed with the 736 text "X-". 738 Servers MUST support the use of non-standard properties and 739 parameters in address object resources stored via the PUT method. 741 Servers may need to enforce rules for their own "private" properties 742 or parameters, so servers MAY reject any attempt by the client to 743 change those or use values for those outside of any restrictions the 744 server may have. Servers SHOULD ensure that any "private" properties 745 or parameters it uses follow the convention of including a vendor id 746 in the "X-" name, as described in Section 3.8 of [RFC2426], e.g., 747 "X-ABC-PRIVATE". 749 6.3.2.3. Address Object Resource Entity Tag 751 The DAV:getetag property MUST be defined and set to a strong entity 752 tag on all address object resources. 754 A response to a GET request targeted at an address object resource 755 MUST contain an ETag response header field indicating the current 756 value of the strong entity tag of the address object resource. 758 Servers SHOULD return a strong entity tag (ETag header) in a PUT 759 response when the stored address object resource is equivalent by 760 octet equality to the address object resource submitted in the body 761 of the PUT request. This allows clients to reliably use the returned 762 strong entity tag for data synchronization purposes. For instance, 763 the client can do a PROPFIND request on the stored address object 764 resource and have the DAV:getetag property returned, and compare that 765 value with the strong entity tag it received on the PUT response, and 766 know that if they are equal, then the address object resource on the 767 server has not been changed. 769 In the case where the data stored by a server as a result of a PUT 770 request is not equivalent by octet equality to the submitted address 771 object resource, the behavior of the ETag response header is not 772 specified here, with the exception that a strong entity tag MUST NOT 773 be returned in the response. As a result, clients may need to 774 retrieve the modified address object resource (and ETag) as a basis 775 for further changes, rather than use the address object resource it 776 had sent with the PUT request. 778 7. Address Book Access Control 780 CardDAV servers MUST support and adhere to the requirements of WebDAV 781 ACL [RFC3744]. WebDAV ACL provides a framework for an extensible set 782 of privileges that can be applied to WebDAV collections and ordinary 783 resources. 785 7.1. Additional Principal Properties 787 This section defines additional properties for WebDAV principal 788 resources as defined in [RFC3744]. 790 7.1.1. CARDDAV:addressbook-home-set Property 791 Name: addressbook-home-set 793 Namespace: urn:ietf:params:xml:ns:carddav 795 Purpose: Identifies the URL of any WebDAV collections that contain 796 address book collections owned by the associated principal 797 resource. 799 Protected: MAY be protected if the server has fixed locations in 800 which address books are created. 802 COPY/MOVE behavior: This property value MUST be preserved in COPY 803 and MOVE operations. 805 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop 806 request. 808 Description: The CARDDAV:addressbook-home-set property is meant to 809 allow users to easily find the address book collections owned by 810 the principal. Typically, users will group all the address book 811 collections that they own under a common collection. This 812 property specifies the URL of collections that either are address 813 book collections or ordinary collections that have child or 814 descendant address book collections owned by the principal. 816 Definition: 818 820 Example: 822 824 http://addressbook.example.com/bernard/addresses/< 825 /D:href> 826 828 7.1.2. CARDDAV:principal-address Property 830 Name: principal-address 832 Namespace: urn:ietf:params:xml:ns:carddav 834 Purpose: Identifies the URL of an address object resource that 835 corresponds to the user represented by the principal. 837 Protected: MAY be protected if the server provides a fixed location 838 for principal addresses. 840 COPY/MOVE behavior: This property value MUST be preserved in COPY 841 and MOVE operations. 843 allprop behavior: SHOULD be returned by a PROPFIND DAV:allprop 844 request. 846 Description: The CARDDAV:principal-address property is meant to 847 allow users to easily find contact information for users 848 represented by principals on the system. This property specifies 849 the URL of the resource containing the corresponding contact 850 information. The resource could be an address object resource in 851 an address book collection, or it could be a resource in a 852 "regular" collection. 854 Definition: 856 858 Example: 860 862 http://addressbook.example.com/system/cyrus.vcf< 863 /D:href> 864 866 8. Address Book Reports 868 This section defines the reports that CardDAV servers MUST support on 869 address book collections and address object resources. 871 CardDAV servers MUST advertise support for these REPORTs on all 872 address book collections and address object resources with the DAV: 873 supported-report-set property defined in Section 3.1.5 of [RFC3253]. 874 CardDAV servers MAY also advertise support for these REPORTs on 875 ordinary collections. 877 Some of these REPORTs allow address data (from possibly multiple 878 resources) to be returned. 880 8.1. REPORT Method 882 The REPORT method (defined in Section 3.6 of [RFC3253]) provides an 883 extensible mechanism for obtaining information about a resource. 885 Unlike the PROPFIND method, which returns the value of one or more 886 named properties, the REPORT method can involve more complex 887 processing. REPORT is valuable in cases where the server has access 888 to all of the information needed to perform the complex request (such 889 as a query), and where it would require multiple requests for the 890 client to retrieve the information needed to perform the same 891 request. 893 A server that supports this specification MUST support the DAV: 894 expand-property report (defined in Section 3.8 of [RFC3253]). 896 8.2. Ordinary Collections 898 Servers MAY support the REPORTs defined in this document on ordinary 899 collections (collections that are not address book collections) in 900 addition to address book collections or address object resources. In 901 computing responses to the REPORTs on ordinary collections, servers 902 MUST only consider address object resources contained in address book 903 collections that are targeted by the REPORT based on the value of the 904 Depth request header. 906 8.3. Searching Text: Collations 908 Some of the reports defined in this section do text matches of 909 character strings provided by the client and compared to stored 910 address data. Since vCard data is by default encoded in the UTF-8 911 charset and may include characters outside of the US-ASCII charset 912 range in some property and parameter values, there is a need to 913 ensure that text matching follows well-defined rules. 915 To deal with this, this specification makes use of the IANA Collation 916 Registry defined in [RFC4790] to specify collations that may be used 917 to carry out the text comparison operations with a well-defined rule. 919 Collations supported by the server MUST support "equality" and 920 "substring" match operations as per [RFC4790] Section 4.2, including 921 the "prefix" and "suffix" options for "substring" matching. CardDAV 922 uses these match options for "equals", "contains", "starts-with" and 923 "ends-with" match operations. 925 CardDAV servers are REQUIRED to support the "i;ascii-casemap" 926 [RFC4790] and "i;unicode-casemap" [RFC5051] collations, and MAY 927 support other collations. 929 Servers MUST advertise the set of collations that they support via 930 the CARDDAV:supported-collation-set property defined on any resource 931 that supports reports that use collations. 933 In the absence of a collation explicitly specified by the client, or 934 if the client specifies the "default" collation identifier (as 935 defined in [RFC4790] Section 3.1), the server MUST default to using 936 "i;unicode-casemap" as the collation. 938 Wildcards (as defined in [RFC4790] Section 3.2) MUST NOT be used in 939 the collation identifier. 941 If the client chooses a collation not supported by the server, the 942 server MUST respond with a CARDDAV:supported-collation precondition 943 error response. 945 8.3.1. CARDDAV:supported-collation-set Property 947 Name: supported-collation-set 949 Namespace: urn:ietf:params:xml:ns:carddav 951 Purpose: Identifies the set of collations supported by the server 952 for text matching operations. 954 Protected: MUST be protected as it indicates support provided by the 955 server. 957 COPY/MOVE behavior: This property value MUST be preserved in COPY 958 and MOVE operations. 960 allprop behavior: SHOULD be returned by a PROPFIND DAV:allprop 961 request. 963 Description: The CARDDAV:supported-collation-set property contains 964 zero or more CARDDAV:supported-collation elements which specify 965 the collection identifiers of the collations supported by the 966 server. 968 Definition: 970 972 974 Example: 976 978 i;ascii-casemap 979 i;octet 980 i;unicode-casemap 982 984 8.4. Partial Retrieval 986 Some address book REPORTs defined in this document allow partial 987 retrieval of address object resources. A CardDAV client can specify 988 what information to return in the body of an address book REPORT 989 request. 991 A CardDAV client can request particular WebDAV property values, all 992 WebDAV property values, or a list of the names of the resource's 993 WebDAV properties. A CardDAV client can also request address data to 994 be returned and whether all vCard properties should be returned or 995 only particular ones. See CARDDAV:address-data in Section 10.4. 997 8.5. Non-standard Properties and Parameters 999 Servers MUST support the use of non-standard property or parameter 1000 names in the CARDDAV:address-data XML element in address book REPORT 1001 requests to allow clients to request that non-standard properties and 1002 parameters be returned in the address data provided in the response. 1004 Servers MAY support the use of non-standard property or parameter 1005 names in the CARDDAV:prop-filter and CARDDAV:param-filter XML 1006 elements specified in the CARDDAV:filter XML element of address book 1007 REPORT requests. 1009 Servers MUST fail with the CARDDAV:supported-filter precondition if 1010 an address book REPORT request uses a CARDDAV:prop-filter or CARDDAV: 1011 param-filter XML element that makes reference to a non-standard 1012 property or parameter name which the server does not support queries 1013 on. 1015 8.6. CARDDAV:addressbook-query Report 1017 The CARDDAV:addressbook-query REPORT performs a search for all 1018 address object resources that match a specified filter. The response 1019 of this REPORT will contain all the WebDAV properties and address 1020 object resource data specified in the request. In the case of the 1021 CARDDAV:address-data XML element, one can explicitly specify the 1022 vCard properties that should be returned in the address object 1023 resource data that matches the filter. 1025 The format of this report is modeled on the PROPFIND method. The 1026 request and response bodies of the CARDAV:addressbook-query report 1027 use XML elements that are also used by PROPFIND. In particular the 1028 request can include XML elements to request WebDAV properties to be 1029 returned. When that occurs the response should follow the same 1030 behavior as PROPFIND with respect to the DAV:multistatus response 1031 elements used to return specific property results. For instance, a 1032 request to retrieve the value of a property which does not exist is 1033 an error and MUST be noted with a response XML element which contains 1034 a 404 (Not Found) status value. 1036 Support for the CARDDAV:addressbook-query REPORT is REQUIRED. 1038 Marshalling: 1040 The request body MUST be a CARDDAV:addressbook-query XML element 1041 as defined in Section 10.3. 1043 The request MAY include a Depth header. If no Depth header is 1044 included, Depth:0 is assumed. 1046 The response body for a successful request MUST be a DAV: 1047 multistatus XML element (i.e., the response uses the same format 1048 as the response for PROPFIND). In the case where there are no 1049 response elements, the returned DAV:multistatus XML element is 1050 empty. 1052 The response body for a successful CARDDAV:addressbook-query 1053 REPORT request MUST contain a DAV:response element for each 1054 address object that matched the search filter. address data is 1055 returned in the CARDDAV:address-data XML element inside the DAV: 1056 propstat XML element. 1058 Preconditions: 1060 (CARDDAV:supported-address-data): The attributes "content-type" 1061 and "version" of the CARDDAV:address-data XML element (see 1062 Section 10.4) specify a media type supported by the server for 1063 address object resources. 1065 (CARDDAV:supported-filter): The CARDDAV:prop-filter (see 1066 Section 10.5.1) and CARDDAV:param-filter (see Section 10.5.2) XML 1067 elements used in the CARDDAV:filter XML element (see Section 10.5) 1068 in the REPORT request only make reference to properties and 1069 parameters for which queries are supported by the server. i.e., if 1070 the CARDDAV:filter element attempts to reference an unsupported 1071 property or parameter, this precondition is violated. Servers 1072 SHOULD report the CARDDAV:prop-filter or CARDDAV:param-filter for 1073 which it does not provide support. 1075 1078 (CARDDAV:supported-collation): Any XML attribute specifying a 1079 collation MUST specify a collation supported by the server as 1080 described in Section 8.3. 1082 Postconditions: 1084 (DAV:number-of-matches-within-limits): The number of matching 1085 address object resources must fall within server-specific, 1086 predefined limits. For example, this condition might be triggered 1087 if a search specification would cause the return of an extremely 1088 large number of responses. 1090 8.6.1. Limiting Results 1092 A client can limit the number of results returned by the server 1093 through use of the CARDDAV:limit element in the request body. This 1094 is useful when clients are only interested in a few matches, or only 1095 have limited space to display results to users and thus don't need 1096 the overhead of receiving more than that. When the results are 1097 truncated by the server, the server MUST follow the rules below for 1098 indicating a result set truncation to the client. 1100 8.6.2. Truncation of Results 1102 A server MAY limit the number of resources in a response, for 1103 example, to limit the amount of work expended in processing a query, 1104 or as the result of an explicit limit set by the client. If it does 1105 so, the response MUST use status code 207, return a DAV:multistatus 1106 response body, and indicate a status of 507 (Insufficient Storage) 1107 for the request URI. That DAV:response element SHOULD include a DAV: 1108 error element with the DAV:number-of-matches-within-limits pre- 1109 condition, as defined in [RFC3744] (Section 9.2). 1111 The server SHOULD also include the partial results in additional DAV: 1112 response elements. If a client requested limit is being applied, the 1113 507 response for the request URI MUST NOT be included in calculating 1114 the limit (e.g., if the client requests that only a single result be 1115 returned, and multiple matches are present, then the DAV:multistatus 1116 response will include one DAV:response for the matching resource and 1117 one DAV:response for the 507 status on the request URI). 1119 8.6.3. Example: Partial Retrieval of vCards Matching NICKNAME 1121 In this example, the client requests the server to search for address 1122 object resources that contain a NICKNAME property whose value equals 1123 some specific text, and to return specific vCard properties for those 1124 vCards found. In addition the DAV:getetag property is also requested 1125 and returned as part of the response. 1127 >> Request << 1129 REPORT /home/bernard/addressbook/ HTTP/1.1 1130 Host: addressbook.example.com 1131 Depth: 1 1132 Content-Type: text/xml; charset="utf-8" 1133 Content-Length: xxxx 1135 1136 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 me 1153 1154 1155 1156 >> Response << 1158 HTTP/1.1 207 Multi-Status 1159 Date: Sat, 11 Nov 2006 09:32:12 GMT 1160 Content-Type: text/xml; charset="utf-8" 1161 Content-Length: xxxx 1163 1164 1166 1167 /home/bernard/addressbook/v102.vcf 1168 1169 1170 "23ba4d-ff11fb" 1171 BEGIN:VCARD 1172 VERSION:3.0 1173 NICKNAME:me 1174 UID:34222-232@example.com 1175 FN:Cyrus Daboo 1176 EMAIL:daboo@example.com 1177 END:VCARD 1178 1179 1180 HTTP/1.1 200 OK 1181 1182 1183 1185 8.6.4. Example: Partial Retrieval of vCards Matching a Full Name or 1186 Email Address 1188 In this example, the client requests the server to search for address 1189 object resources that contain a FN property whose value contains some 1190 specific text or that contain an EMAIL property whose value contains 1191 other text, and to return specific vCard properties for those vCards 1192 found. In addition the DAV:getetag property is also requested and 1193 returned as part of the response. 1195 >> Request << 1197 REPORT /home/bernard/addressbook/ HTTP/1.1 1198 Host: addressbook.example.com 1199 Depth: 1 1200 Content-Type: text/xml; charset="utf-8" 1201 Content-Length: xxxx 1203 1204 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 daboo 1221 1222 1223 daboo 1226 1227 1228 1229 >> Response << 1231 HTTP/1.1 207 Multi-Status 1232 Date: Sat, 11 Nov 2006 09:32:12 GMT 1233 Content-Type: text/xml; charset="utf-8" 1234 Content-Length: xxxx 1236 1237 1239 1240 /home/bernard/addressbook/v102.vcf 1241 1242 1243 "23ba4d-ff11fb" 1244 BEGIN:VCARD 1245 VERSION:3.0 1246 NICKNAME:me 1247 UID:34222-232@example.com 1248 FN:David Boo 1249 EMAIL:daboo@example.com 1250 END:VCARD 1251 1252 1253 HTTP/1.1 200 OK 1254 1255 1256 1257 /home/bernard/addressbook/v104.vcf 1258 1259 1260 "23ba4d-ff11fc" 1261 BEGIN:VCARD 1262 VERSION:3.0 1263 NICKNAME:oliver 1264 UID:34222-23222@example.com 1265 FN:Oliver Daboo 1266 EMAIL:oliver@example.com 1267 END:VCARD 1268 1269 1270 HTTP/1.1 200 OK 1271 1272 1273 1275 8.6.5. Example: Truncated Results 1277 In this example, the client requests the server to search for address 1278 object resources that contain a FN property whose value contains some 1279 specific text, and to return the DAV:getetag property for two results 1280 only. The server response includes a 507 status for the request URI 1281 indicating that there were more than two resources that matched the 1282 query, but that the server truncated the result set as requested by 1283 the client. 1285 >> Request << 1287 REPORT /home/bernard/addressbook/ HTTP/1.1 1288 Host: addressbook.example.com 1289 Depth: 1 1290 Content-Type: text/xml; charset="utf-8" 1291 Content-Length: xxxx 1293 1294 1296 1297 1298 1299 1300 1301 daboo 1304 1305 1306 1307 2 1308 1309 1310 >> Response << 1312 HTTP/1.1 207 Multi-Status 1313 Date: Sat, 11 Nov 2006 09:32:12 GMT 1314 Content-Type: text/xml; charset="utf-8" 1315 Content-Length: xxxx 1317 1318 1320 1321 /home/bernard/addressbook/ 1322 HTTP/1.1 507 OK 1323 1324 1325 Only two matching records were returned 1326 1327 1328 1329 /home/bernard/addressbook/v102.vcf 1330 1331 1332 "23ba4d-ff11fb" 1333 1334 HTTP/1.1 200 OK 1335 1336 1337 1338 /home/bernard/addressbook/v104.vcf 1339 1340 1341 "23ba4d-ff11fc" 1342 1343 HTTP/1.1 200 OK 1344 1345 1346 1348 8.7. CARDDAV:addressbook-multiget Report 1350 The CARDDAV:addressbook-multiget REPORT is used to retrieve specific 1351 address object resources from within a collection, if the Request-URI 1352 is a collection, or to retrieve a specific address object resource, 1353 if the Request-URI is a address object resource. This report is 1354 similar to the CARDDAV:addressbook-query REPORT (see Section 8.6), 1355 except that it takes a list of DAV:href elements instead of a 1356 CARDDAV:filter element to determine which address object resources to 1357 return. 1359 Support for the addressbook-multiget REPORT is REQUIRED. 1361 Marshalling: 1363 The request body MUST be a CARDDAV:addressbook-multiget XML 1364 element (see Section 10.7, which MUST contain at least one DAV: 1365 href XML element, and one optional CARDDAV:address-data element as 1366 defined in Section 10.4. If the Request-URI is a collection 1367 resource, then the DAV:href elements MUST refer to resources 1368 within that collection, and they MAY refer to resources at any 1369 depth within the collection. As a result the "Depth" header MUST 1370 be ignored by the server and SHOULD NOT be sent by the client. If 1371 the Request-URI refers to a non-collection resource, then there 1372 MUST be a single DAV:href element that is equivalent to the 1373 Request-URI. 1375 The response body for a successful request MUST be a DAV: 1376 multistatus XML element. 1378 The response body for a successful CARDDAV:addressbook-multiget 1379 REPORT request MUST contain a DAV:response element for each 1380 address object resource referenced by the provided set of DAV:href 1381 elements. Address data is returned in the CARDDAV:address-data 1382 element inside the DAV:prop element. 1384 In the case of an error accessing any of the provided DAV:href 1385 resources, the server MUST return the appropriate error status 1386 code in the DAV:status element of the corresponding DAV:response 1387 element. 1389 Preconditions: 1391 (CARDAV:supported-address-data): The attributes "content-type" and 1392 "version" of the CARDDAV:address-data XML elements (see 1393 Section 10.4) specify a media type supported by the server for 1394 address object resources. 1396 Postconditions: 1398 None. 1400 8.7.1. Example: CARDDAV:addressbook-multiget Report 1402 In this example, the client requests the server to return specific 1403 properties of the address components referenced by specific URIs. In 1404 addition the DAV:getetag property is also requested and returned as 1405 part of the response. Note that in this example, the resource at 1406 http://addressbook.example.com/home/bernard/addressbook/vcf1.vcf does 1407 not exist, resulting in an error status response. 1409 >> Request << 1411 REPORT /home/bernard/addressbook/ HTTP/1.1 1412 Host: addressbook.example.com 1413 Content-Type: text/xml; charset="utf-8" 1414 Content-Length: xxxx 1416 1417 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 /home/bernard/addressbook/vcf102.vcf 1430 /home/bernard/addressbook/vcf1.vcf 1431 1432 >> Response << 1434 HTTP/1.1 207 Multi-Status 1435 Date: Sat, 11 Nov 2006 09:32:12 GMT 1436 Content-Type: text/xml; charset="utf-8" 1437 Content-Length: xxxx 1439 1440 1442 1443 /home/bernard/addressbook/vcf102.vcf 1444 1445 1446 "23ba4d-ff11fb" 1447 BEGIN:VCARD 1448 VERSION:3.0 1449 NICKNAME:me 1450 UID:34222-232@example.com 1451 FN:Cyrus Daboo 1452 EMAIL:daboo@example.com 1453 END:VCARD 1454 1455 1456 HTTP/1.1 200 OK 1457 1458 1459 1460 /home/bernard/addressbook/vcf1.vcf 1461 HTTP/1.1 404 Resource not found 1462 1463 1465 9. Guidelines 1467 9.1. Restrict the Properties Returned 1469 Clients may not need all the properties in a vCard object when 1470 presenting information to the user, or looking up specific items for 1471 their email address, for example. Since some property data can be 1472 large (e.g., PHOTO or SOUND with inline content) clients can choose 1473 to ignore those by only requesting the specific items it knows it 1474 will use, through use of the CARDDAV:address-data XML element in the 1475 relevant reports. 1477 However, if a client needs to make a change to a vCard, it can only 1478 change the entire vCard data via a PUT request. There is no way to 1479 incrementally make a change to a set of properties within a vCard 1480 object resource. As a result the client will have to cache the 1481 entire set of properties on a resource that is being changed. 1483 9.2. Use of Locking 1485 WebDAV locks can be used to prevent two clients modifying the same 1486 resource from either overwriting each others' changes (though that 1487 problem can also be solved by using ETags) and also to prevent the 1488 user from making changes that will conflict with another set of 1489 changes. In a multi-user address book system, the address book 1490 client could lock an address object resource while the user is 1491 editing the vCard data, and unlock the address object resource when 1492 the user finishes or cancels. Locks can also be used to prevent 1493 changes while data is being reorganized. For example, an address 1494 book client might lock two address book collections prior to moving a 1495 bunch of address object resources from one to another. 1497 Clients may request a lock timeout period that is appropriate to the 1498 use case. When the user explicitly decides to reserve a resource and 1499 prevent other changes, a long timeout might be appropriate, but in 1500 cases when the client automatically decides to lock the resource the 1501 timeout should be short (and the client can always refresh the lock 1502 should it need to). A short lock timeout means that if the client is 1503 unable to remove the lock, the other address book users aren't 1504 prevented from making changes. 1506 9.3. Client Configuration 1508 When CardDAV clients need to be configured, the key piece of 1509 information that they require is the principal-URL of the user whose 1510 addressbook information is desired. Servers SHOULD support the DAV: 1511 current-user-principal-URL property as defined in [RFC5397] to give 1512 clients a fast way to locate user principals. 1514 Given support for SRV records (Section 11) and DAV:current-user- 1515 principal-URL [RFC5397], users only need enter a user identifier, 1516 host name and password to configure their client. The client would 1517 take the host name and do an SRV lookup to locate the CardDAV server, 1518 then execute an authenticated PROPFIND on the root / resource looking 1519 for the DAV:current-user-principal-URL property. The value returned 1520 gives the client direct access to the user's principal-URL and from 1521 there all the related CardDAV properties needed to locate address 1522 books. 1524 9.4. Finding Other Users' Address Books 1526 For address book sharing use cases, one might wish to find the 1527 address book belonging to another user. If the other user has an 1528 address book in the same repository, that address book can be found 1529 by using the principal namespace required by WebDAV ACL support. 1531 To find other users' address books, the DAV:principal-property-search 1532 REPORT can be used to filter on some properties and return others. 1533 To search for an address book owned by a user named "Laurie", the 1534 REPORT request body would look like this: 1536 1537 1538 1539 1540 1541 1542 Laurie 1543 1544 1545 1547 1548 1549 1551 The server performs a case-sensitive or caseless search for a 1552 matching string subset of "Laurie" within the DAV:displayname 1553 property. Thus, the server might return "Laurie Dusseault", "Laurier 1554 Desruisseaux" or "Wilfrid Laurier" all as matching DAV:displayname 1555 values, and the address books for each of these. 1557 10. XML Element Definitions 1559 10.1. CARDDAV:addressbook XML Element 1561 Name: addressbook 1563 Namespace: urn:ietf:params:xml:ns:carddav 1565 Purpose: Specifies the resource type of an address book collection. 1567 Description: See Section 5.2. 1569 Definition: 1571 1573 10.2. CARDDAV:supported-collation XML Element 1575 Name: supported-collation 1577 Namespace: urn:ietf:params:xml:ns:carddav 1579 Purpose: Identifies a single collation via its collation identifier 1580 as defined by [RFC4790]. 1582 Description: The CARDDAV:supported-collation contains the text of a 1583 collation identifier as described in Section 8.3.1. 1585 Definition: 1587 1588 1590 10.3. CARDDAV:addressbook-query XML Element 1592 Name: addressbook-query 1594 Namespace: urn:ietf:params:xml:ns:carddav 1596 Purpose: Defines a report for querying address book data 1598 Description: See Section 8.6. 1600 Definition: 1602 1606 10.4. CARDDAV:address-data XML Element 1608 Name: address-data 1610 Namespace: urn:ietf:params:xml:ns:carddav 1612 Purpose: Specifies one of the following: 1614 1. A supported media type for address object resources when 1615 nested in the CARDDAV:supported-address-data property; 1617 2. The parts of an address object resource should be returned by 1618 a given address book REPORT; 1620 3. The content of an address object resource in a response to an 1621 address book REPORT. 1623 Description: When nested in the CARDDAV:supported-address-data 1624 property, the CARDDAV:address-data XML element specifies a media 1625 type supported by the CardDAV server for address object resources. 1627 When used in an address book REPORT request, the CARDDAV:address- 1628 data XML element specifies which parts of address object resources 1629 need to be returned in the response. If the CARDDAV:address-data 1630 XML element doesn't contain any CARDDAV:prop elements, address 1631 object resources will be returned in their entirety. 1633 Finally, when used in an address book REPORT response, the 1634 CARDDAV:address-data XML element specifies the content of a 1635 address object resource. Given that XML parsers normalize the 1636 two-character sequence CRLF (US-ASCII decimal 13 and US-ASCII 1637 decimal 10) to a single LF character (US-ASCII decimal 10), the CR 1638 character (US-ASCII decimal 13) MAY be omitted in address object 1639 resources specified in the CARDDAV:address-data XML element. 1640 Furthermore, address object resources specified in the CARDDAV: 1641 address-data XML element MAY be invalid per their media type 1642 specification if the CARDAV:address-data XML element part of the 1643 address book REPORT request did not specify required properties 1644 (e.g., UID, etc.) or specified a CARDDAV:prop XML element with the 1645 "novalue" attribute set to "yes". 1647 Note: The CARDDAV:address-data XML element is specified in requests 1648 and responses inside the DAV:prop XML element as if it were a 1649 WebDAV property. However, the CARDDAV:address-data XML element is 1650 not a WebDAV property and as such it is not returned in PROPFIND 1651 responses nor used in PROPPATCH requests. 1653 Note: The address data embedded within the CARDDAV:address-data XML 1654 element MUST follow the standard XML character data encoding 1655 rules, including use of <, >, & etc entity encoding or 1656 the use of a construct. In the later case the 1657 vCard data cannot contain the character sequence "]]>" which is 1658 the end delimiter for the CDATA section. 1660 Definition: 1662 1664 when nested in the CARDDAV:supported-address-data property 1665 to specify a supported media type for address object 1666 resources; 1668 1670 when nested in the DAV:prop XML element in an addressbook 1671 REPORT request to specify which parts of address object 1672 resources should be returned in the response; 1674 1675 1677 when nested in the DAV:prop XML element in an addressbook 1678 REPORT response to specify the content of a returned 1679 address object resource. 1681 1683 1684 1686 attributes can be used on all three variants of the 1687 CALDAV:address-data XML element. 1689 10.4.1. CARDDAV:allprop XML Element 1691 Name: allprop 1693 Namespace: urn:ietf:params:xml:ns:carddav 1695 Purpose: Specifies that all properties shall be returned. 1697 Description: This element can be used when the client wants all 1698 properties of components returned by a report. 1700 Definition: 1702 1704 NOTE: The CARDDAV:allprop element defined here has the same name as 1705 the DAV:allprop element defined in WebDAV. However, the CARDDAV: 1706 allprop element defined here uses the 1707 "urn:ietf:params:xml:ns:carddav" namespace, as opposed to the "DAV:" 1708 namespace used for the DAV:allprop element defined in WebDAV. 1710 10.4.2. CARDDAV:prop XML Element 1712 Name: prop 1714 Namespace: urn:ietf:params:xml:ns:carddav 1716 Purpose: Defines which properties to return in the response. 1718 Description: The "name" attribute specifies the name of the vCard 1719 property to return (e.g., "NICKNAME"). The "novalue" attribute 1720 can be used by clients to request that the actual value of the 1721 property not be returned (if the "novalue" attribute is set to 1722 "yes"). In that case the server will return just the vCard 1723 property name and any vCard parameters and a trailing ":" without 1724 the subsequent value data. 1726 vCard allows a "group" prefix to appear before a property name in 1727 the vCard data. When the "name" attribute does not specify a 1728 group prefix, it MUST match properties in the vCard data without a 1729 group prefix or with any group prefix. When the "name" attribute 1730 includes a group prefix, it MUST match properties that have 1731 exactly the same group prefix and name. e.g.: a "name" set to 1732 "TEL" will match "TEL", "X-ABC.TEL", "X-ABC-1.TEL" vCard 1733 properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL" 1734 vCard property only, it will not match "TEL" or "X-ABC-1.TEL". 1736 Definition: 1738 1740 1742 1743 1745 NOTE: The CARDDAV:prop element defined here has the same name as the 1746 DAV:prop element defined in WebDAV. However, the CARDDAV:prop 1747 element defined here uses the "urn:ietf:params:xml:ns:carddav" 1748 namespace, as opposed to the "DAV:" namespace used for the DAV:prop 1749 element defined in WebDAV. 1751 10.5. CARDDAV:filter XML Element 1753 Name: filter 1754 Namespace: urn:ietf:params:xml:ns:carddav 1756 Purpose: Determines which matching objects are returned. 1758 Description: The "filter" element specifies the search filter used 1759 to match address objects that should be returned by a report. The 1760 "test" attribute specifies whether any (logical OR) or all 1761 (logical AND) of the prop-filter tests needs to match in order for 1762 the overall filter to match. 1764 Definition: 1766 1768 1769 1773 10.5.1. CARDDAV:prop-filter XML Element 1775 Name: prop-filter 1777 Namespace: urn:ietf:params:xml:ns:carddav 1779 Purpose: Limits the search to specific properties. 1781 Description: The CARDDAV:prop-filter XML element specifies a search 1782 criteria on a specific vCard property (e.g., NICKNAME). An 1783 address object is said to match a CARDDAV:prop-filter if: 1785 * A property of the type specified by the "name" attribute 1786 exists, and the CARDDAV:prop-filter is empty, or it matches any 1787 CARDDAV:text-match conditions if specified, and that CARDDAV: 1788 param-filter child elements also match. The "test" attribute 1789 specifies whether any (logical OR) or all (logical AND) of the 1790 text-filter and param-filter tests need to match in order for 1791 the overall filter to match. 1793 or: 1795 * A property of the type specified by the "name" attribute does 1796 not exist, and the CARDAV:is-not-defined element is specified. 1798 vCard allows a "group" prefix to appear before a property name in 1799 the vCard data. When the "name" attribute does not specify a 1800 group prefix, it MUST match properties in the vCard data without a 1801 group prefix or with any group prefix. When the "name" attribute 1802 includes a group prefix, it MUST match properties that have 1803 exactly the same group prefix and name. e.g.: a "name" set to 1804 "TEL" will match "TEL", "X-ABC.TEL", "X-ABC-1.TEL" vCard 1805 properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL" 1806 vCard property only, it will not match "TEL" or "X-ABC-1.TEL". 1808 Definition: 1810 1813 1815 1820 10.5.2. CARDDAV:param-filter XML Element 1822 Name: param-filter 1824 Namespace: urn:ietf:params:xml:ns:carddav 1826 Purpose: Limits the search to specific parameter values. 1828 Description: The CARDDAV:param-filter XML element specifies a search 1829 criteria on a specific vCard property parameter (e.g., TYPE) in 1830 the scope of a given CARDDAV:prop-filter. A vCard property is 1831 said to match a CARDDAV:param-filter if: 1833 * A parameter of the type specified by the "name" attribute 1834 exists, and the CARDDAV:param-filter is empty, or it matches 1835 the CARDDAV:text-match conditions if specified. 1837 or: 1839 * A parameter of the type specified by the "name" attribute does 1840 not exist, and the CARDDAV:is-not-defined element is specified. 1842 Definition: 1844 1846 1847 1849 10.5.3. CARDDAV:is-not-defined XML Element 1851 Name: is-not-defined 1853 Namespace: urn:ietf:params:xml:ns:carddav 1855 Purpose: Specifies that a match should occur if the enclosing 1856 property or parameter does not exist. 1858 Description: The CARDDAV:is-not-defined XML element specifies that a 1859 match occurs if the enclosing property or parameter value 1860 specified in an address book REPORT request does not exist in the 1861 address data being tested. 1863 Definition: 1865 1867 10.5.4. CARDDAV:text-match XML Element 1869 Name: text-match 1871 Namespace: urn:ietf:params:xml:ns:carddav 1873 Purpose: Specifies a substring match on a property or parameter 1874 value. 1876 Description: The CARDDAV:text-match XML element specifies text used 1877 for a substring match against the property or parameter value 1878 specified in an address book REPORT request. 1880 The "collation" attribute is used to select the collation that the 1881 server MUST use for character string matching. In the absence of 1882 this attribute the server MUST use the "i;unicode-casemap" 1883 collation. 1885 The "negate-condition" attribute is used to indicate that this 1886 test returns a match if the text matches, when the attribute value 1887 is set to "no", or return a match if the text does not match, if 1888 the attribute value is set to "yes". For example, this can be 1889 used to match components with a CATEGORIES property not set to 1890 PERSON. 1892 The "match-type" attribute is used to indicate the type of match 1893 operation to use. Possible choices are: 1895 "equals" - an exact match to the target string 1897 "contains" - a substring match, matching anywhere within the 1898 target string 1900 "starts-with" - a substring match, matching only at the start 1901 of the target string 1903 "ends-with" - a substring match, matching only at the end of 1904 the target string 1906 Definition: 1908 1909 1911 1916 10.6. CARDDAV:limit XML Element 1918 Name: limit 1920 Namespace: urn:ietf:params:xml:ns:carddav 1922 Purpose: Specifies different types of limits that can be applied to 1923 the results returned by the server. 1925 Description: The CARDDAV:limit XML element can be used to specify 1926 different types of limits that the client can request the server 1927 to apply to the results returned by the server. Currently only 1928 the CARDDAV:nresults limit can be used, other types of limit could 1929 be defined in the future. 1931 Definition: 1933 1935 10.6.1. CARDDAV:nresults XML Element 1937 Name: nresults 1939 Namespace: urn:ietf:params:xml:ns:carddav 1941 Purpose: Specifies a limit on the number of results returned by the 1942 server. 1944 Description: The CARDDAV:nresults XML element contains a requested 1945 maximum number of DAV:response elements to be returned in the 1946 response body of a query. The server MAY disregard this limit. 1947 The value of this element is an unsigned integer. 1949 Definition: 1951 1952 1954 10.7. CARDDAV:addressbook-multiget XML Element 1956 Name: addressbook-multiget 1958 Namespace: urn:ietf:params:xml:ns:carddav 1960 Purpose: CardDAV report used to retrieve specific address objects 1961 via their URIs. 1963 Description: See Section 8.7. 1965 Definition: 1967 1972 11. Service Discovery via SRV Records 1974 [RFC2782] defines a DNS-based service discovery protocol that has 1975 been widely adopted as a means of locating particular services within 1976 a local area network and beyond, using SRV RR records. 1978 This specification adds two service types for use with SRV records: 1980 carddav: Identifies a CardDAV server that uses HTTP without SSL. 1982 carddavs: Identifies a CardDAV server that uses HTTP with SSL. 1984 Example: non-SSL service record 1986 _carddav._tcp SRV 0 1 80 addressbook.example.com. 1988 Example: SSL service 1990 _carddavs._tcp SRV 0 1 443 addressbook.example.com. 1992 12. Internationalization Considerations 1994 CardDAV allows internationalized strings to be stored and retrieved 1995 for the description of address book collections (see Section 6.2.1). 1997 The CARDDAV:addressbook-query report (Section 8.6) includes a text 1998 searching option controlled by the CARDDAV:text-match element and 1999 details of character handling are covered in the description of that 2000 element (see Section 10.5.4). 2002 13. Security Considerations 2004 HTTP protocol transactions are sent in the clear over the network 2005 unless protection from snooping is negotiated. This can be 2006 accomplished by use of TLS as defined in [RFC2818]. In particular, 2007 if HTTP Basic authentication is available, the server MUST allow TLS 2008 to be used at the same time, and SHOULD prevent use of Basic 2009 authentication when TLS is not in use. 2011 With the ACL extension present, WebDAV allows control over who can 2012 access (read or write) any resource on the WebDAV server. In 2013 addition, WebDAV ACL provides for an "inheritance" mechanism, whereby 2014 resources may inherit access privileges from other resources. Often 2015 the "other" resource is a parent collection of the resource itself. 2016 Clients MUST take care to ensure users are aware of which address 2017 books may be "private" (i.e. only accessible to them) and which are 2018 "shared" (i.e. accessible to others). 2020 Since web servers are often the target of automated indexing 2021 applications that gather data from the server, analyze it and extract 2022 'interesting' parts, great care must be taken when allowing 2023 unauthenticated access to any address book or address object data. 2024 Clients MAY choose to warn users when they create address data in a 2025 public address book, copy or move address data into public address 2026 books, or change access privileges in such a way as to expose address 2027 data to unauthenticated users. 2029 This specification currently relies on standard HTTP authentication 2030 mechanisms for identifying users. These comprise Basic and Digest 2031 authentication as well as SSL using client-side certificates. 2033 14. IANA Consideration 2035 In addition to the namespaces defined by RFC4918 [RFC4918] for XML 2036 elements, this document uses a URN to describe a new XML namespace 2037 conforming to a registry mechanism described in RFC3688 [RFC3688]. 2038 All other IANA considerations mentioned in RFC4918 [RFC4918] also 2039 apply to this document. 2041 14.1. Namespace Registration 2043 Registration request for the carddav namespace: 2045 URI: urn:ietf:params:xml:ns:carddav 2047 Registrant Contact: See the "Author's Address" section of this 2048 document. 2050 XML: None. Namespace URIs do not represent an XML specification. 2052 15. Acknowledgments 2054 Thanks go to Lisa Dusseault and Bernard Desruisseaux for their work 2055 on CalDAV, on which CardDAV is heavily based. The following 2056 individuals contributed their ideas and support for writing this 2057 specification: Mike Douglass, Stefan Eissing, Helge Hess, Arnaud 2058 Quillaud, Julian Reschke, Elias Sinderson, Greg Stein, Wilfredo 2059 Sanchez, and Simon Vaillancourt. 2061 16. References 2063 16.1. Normative References 2065 [I-D.ietf-vcarddav-vcardrev] 2066 Perreault, S. and P. Resnick, "vCard Format 2067 Specification", draft-ietf-vcarddav-vcardrev-06 (work in 2068 progress), March 2009. 2070 [I-D.ietf-vcarddav-webdav-mkcol] 2071 Daboo, C., "Extended MKCOL for WebDAV", 2072 draft-ietf-vcarddav-webdav-mkcol-03 (work in progress), 2073 February 2009. 2075 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2076 Requirement Levels", BCP 14, RFC 2119, March 1997. 2078 [RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile", 2079 RFC 2426, September 1998. 2081 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2082 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2083 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2085 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 2086 specifying the location of services (DNS SRV)", RFC 2782, 2087 February 2000. 2089 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2091 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. 2092 Whitehead, "Versioning Extensions to WebDAV 2093 (Web Distributed Authoring and Versioning)", RFC 3253, 2094 March 2002. 2096 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2097 January 2004. 2099 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web 2100 Distributed Authoring and Versioning (WebDAV) 2101 Access Control Protocol", RFC 3744, May 2004. 2103 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 2104 Application Protocol Collation Registry", RFC 4790, 2105 March 2007. 2107 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 2108 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 2110 [RFC5051] Crispin, M., "i;unicode-casemap - Simple Unicode Collation 2111 Algorithm", RFC 5051, October 2007. 2113 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2114 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2116 [RFC5397] Sanchez, W. and C. Daboo, "WebDAV Current Principal 2117 Extension", RFC 5397, December 2008. 2119 [W3C.REC-xml-20060816] 2120 Yergeau, F., Paoli, J., Bray, T., Sperberg-McQueen, C., 2121 and E. Maler, "Extensible Markup Language (XML) 1.0 2122 (Fourth Edition)", World Wide Web Consortium 2123 FirstEdition REC-xml-20060816, August 2006, 2124 . 2126 16.2. Informative References 2128 [IMSP] Myers, J., "IMSP - Internet Message Support Protocol", 2129 June 1995. 2131 [RFC2244] Newman, C. and J. Myers, "ACAP -- Application 2132 Configuration Access Protocol", RFC 2244, November 1997. 2134 [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol 2135 (LDAP): The Protocol", RFC 4511, June 2006. 2137 Appendix A. Change History (to be removed prior to publication as an 2138 RFC) 2140 Changes in -06 2142 1. WGLC: addressbook-home-set changed to SHOULD NOT return in 2143 allprop PROPFIND. 2145 2. WGLC: principal-address description changed to note that the 2146 resource pointed to could be in a regular collection too. 2148 3. Added new section decribing how SRV and current-user-principal 2149 are used to bootstrap client configuration. 2151 4. Removed discussion of using principal-match report. 2153 Changes in -05 2155 1. Removed mailing list discussion note from abstract. 2157 Changes in -04 2159 1. Tweaked limit element text to not imply any formal ordering of 2160 results. 2162 2. Changed prop-filter element to allow zero or more text-match 2163 elements rather than zero or one. 2165 3. Updated to RFC5397 reference. 2167 4. Updated TLS reference to latest version RFC5246. 2169 5. Boiler plate update. 2171 Changes in -03 2173 1. Added limit element to addressbook-query. 2175 2. Specified how a server signals that query results have been 2176 truncated. 2178 3. Minor stylistic changes. 2180 Changes in -02 2182 1. Added text to CARDDAV:prop and CARDDAV:prop-filter elements to 2183 explain how vCard "group" prefix on property names is handled. 2185 Changes in -01 2187 1. Added section on SRV records. 2189 Changes in -00 2191 1. Removed text describing other protocols. 2193 2. Added comment about a new vcard spec being developed. 2195 3. Added SHOULD support for the DAV:current-user-principal-URL 2196 property. 2198 4. Added "anyof"/"allof" test attribute to query XML elements to 2199 support simple or/and combinations of tests. 2201 Changes in pre-04 2203 1. Renamed addressbook-data to address-data for consistency. 2205 2. Fixed address-data element definition. 2207 Changes in pre-03 2209 1. Replaced MKADDRESSBOOK with extended MKCOL. 2211 2. Now require i;uncide-casemap as a supported collation and make it 2212 the default. 2214 3. No longer require i;octet as a supported collation. 2216 4. Allow different types of match operations via the "match-type" 2217 attribute on the "text-match" element. 2219 5. Updated to 4918 reference and removed some text/sections 2220 duplicating 4918. 2222 6. WebDAV Level 3 now required. 2224 7. TLS requirement text tweaked to match latest text approved by 2225 IESG. 2227 8. Added principal-address property to principal resources to allow 2228 a vcard to be associated with a principal. 2230 9. XML definition clean-up. 2232 Changes in pre-02 2234 1. Added commentary on SyncML. 2236 2. Changed 'adbk' to 'addressbook'. 2238 3. Support for MKADDRESSBOOK is now a SHOULD. 2240 4. Updated to RFC4790 reference. 2242 5. Removed synchronization report. 2244 6. Removed BNF conventions section as we have no BNF. 2246 7. Reworded and reformatted several items to match the final CalDAV 2247 spec. 2249 8. Added section on use of nonstandard properties and parameters 2250 (as per CalDAV). 2252 9. Added section of behavior of ETags (as per CalDAV). 2254 10. Generalized the text so that vCard need not be the only format 2255 supported by the server (i.e., allow xml version of vCard etc). 2257 11. Renamed supported-addressbook-data to supported-address-data. 2259 12. Renamed valid-addressbook-data to valid-address-data. 2261 13. Now requires "i;unicasemao" collation. 2263 Changes in pre-01 2265 1. Fixed various incorrect references and typos. 2267 2. Major changes to sync with latest CalDAV spec behaviors. 2269 Author's Address 2271 Cyrus Daboo 2272 Apple Inc. 2273 1 Infinite Loop 2274 Cupertino, CA 95014 2275 USA 2277 Email: cyrus@daboo.name 2278 URI: http://www.apple.com/