aboutsummaryrefslogtreecommitdiffstats
path: root/vendor/sabre/dav/docs/rfc6352.txt
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/sabre/dav/docs/rfc6352.txt')
-rw-r--r--vendor/sabre/dav/docs/rfc6352.txt2691
1 files changed, 2691 insertions, 0 deletions
diff --git a/vendor/sabre/dav/docs/rfc6352.txt b/vendor/sabre/dav/docs/rfc6352.txt
new file mode 100644
index 000000000..cb03747b4
--- /dev/null
+++ b/vendor/sabre/dav/docs/rfc6352.txt
@@ -0,0 +1,2691 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) C. Daboo
+Request for Comments: 6352 Apple
+Category: Standards Track August 2011
+ISSN: 2070-1721
+
+
+ CardDAV: vCard Extensions to
+ Web Distributed Authoring and Versioning (WebDAV)
+
+Abstract
+
+ This document defines extensions to the Web Distributed Authoring and
+ Versioning (WebDAV) protocol to specify a standard way of accessing,
+ managing, and sharing contact information based on the vCard format.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc6352.
+
+Copyright Notice
+
+ Copyright (c) 2011 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+ This document may contain material from IETF Documents or IETF
+ Contributions published or made publicly available before November
+ 10, 2008. The person(s) controlling the copyright in some of this
+ material may not have granted the IETF Trust the right to allow
+
+
+
+Daboo Standards Track [Page 1]
+
+RFC 6352 CardDAV August 2011
+
+
+ modifications of such material outside the IETF Standards Process.
+ Without obtaining an adequate license from the person(s) controlling
+ the copyright in such materials, this document may not be modified
+ outside the IETF Standards Process, and derivative works of it may
+ not be created outside the IETF Standards Process, except to format
+ it for publication as an RFC or to translate it into languages other
+ than English.
+
+Table of Contents
+
+ 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4
+ 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3. Requirements Overview . . . . . . . . . . . . . . . . . . . . 6
+ 4. Address Book Data Model . . . . . . . . . . . . . . . . . . . 7
+ 4.1. Address Book Server . . . . . . . . . . . . . . . . . . . 7
+ 5. Address Book Resources . . . . . . . . . . . . . . . . . . . . 7
+ 5.1. Address Object Resources . . . . . . . . . . . . . . . . . 7
+ 5.1.1. Data Type Conversion . . . . . . . . . . . . . . . . . 8
+ 5.1.1.1. Additional Precondition for GET . . . . . . . . . 8
+ 5.2. Address Book Collections . . . . . . . . . . . . . . . . . 9
+ 6. Address Book Feature . . . . . . . . . . . . . . . . . . . . . 10
+ 6.1. Address Book Support . . . . . . . . . . . . . . . . . . . 10
+ 6.1.1. Example: Using OPTIONS for the Discovery of
+ Support for CardDAV . . . . . . . . . . . . . . . . . 10
+ 6.2. Address Book Properties . . . . . . . . . . . . . . . . . 10
+ 6.2.1. CARDDAV:addressbook-description Property . . . . . . . 10
+ 6.2.2. CARDDAV:supported-address-data Property . . . . . . . 11
+ 6.2.3. CARDDAV:max-resource-size Property . . . . . . . . . . 12
+ 6.3. Creating Resources . . . . . . . . . . . . . . . . . . . . 13
+ 6.3.1. Extended MKCOL Method . . . . . . . . . . . . . . . . 13
+ 6.3.1.1. Example - Successful MKCOL Request . . . . . . . . 14
+ 6.3.2. Creating Address Object Resources . . . . . . . . . . 15
+ 6.3.2.1. Additional Preconditions for PUT, COPY, and
+ MOVE . . . . . . . . . . . . . . . . . . . . . . . 16
+ 6.3.2.2. Non-Standard vCard Properties and Parameters . . . 17
+ 6.3.2.3. Address Object Resource Entity Tag . . . . . . . . 18
+ 7. Address Book Access Control . . . . . . . . . . . . . . . . . 18
+ 7.1. Additional Principal Properties . . . . . . . . . . . . . 18
+ 7.1.1. CARDDAV:addressbook-home-set Property . . . . . . . . 19
+ 7.1.2. CARDDAV:principal-address Property . . . . . . . . . . 19
+ 8. Address Book Reports . . . . . . . . . . . . . . . . . . . . . 20
+ 8.1. REPORT Method . . . . . . . . . . . . . . . . . . . . . . 20
+ 8.2. Ordinary Collections . . . . . . . . . . . . . . . . . . . 21
+ 8.3. Searching Text: Collations . . . . . . . . . . . . . . . . 21
+ 8.3.1. CARDDAV:supported-collation-set Property . . . . . . . 22
+ 8.4. Partial Retrieval . . . . . . . . . . . . . . . . . . . . 23
+ 8.5. Non-Standard Properties and Parameters . . . . . . . . . . 23
+
+
+
+
+Daboo Standards Track [Page 2]
+
+RFC 6352 CardDAV August 2011
+
+
+ 8.6. CARDDAV:addressbook-query Report . . . . . . . . . . . . . 23
+ 8.6.1. Limiting Results . . . . . . . . . . . . . . . . . . . 25
+ 8.6.2. Truncation of Results . . . . . . . . . . . . . . . . 25
+ 8.6.3. Example: Partial Retrieval of vCards Matching
+ NICKNAME . . . . . . . . . . . . . . . . . . . . . . . 26
+ 8.6.4. Example: Partial Retrieval of vCards Matching a
+ Full Name or Email Address . . . . . . . . . . . . . . 27
+ 8.6.5. Example: Truncated Results . . . . . . . . . . . . . . 29
+ 8.7. CARDDAV:addressbook-multiget Report . . . . . . . . . . . 31
+ 8.7.1. Example: CARDDAV:addressbook-multiget Report . . . . . 32
+ 8.7.2. Example: CARDDAV:addressbook-multiget Report . . . . . 33
+ 9. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . 34
+ 9.1. Restrict the Properties Returned . . . . . . . . . . . . . 34
+ 9.2. Avoiding Lost Updates . . . . . . . . . . . . . . . . . . 35
+ 9.3. Client Configuration . . . . . . . . . . . . . . . . . . . 35
+ 9.4. Finding Other Users' Address Books . . . . . . . . . . . . 35
+ 10. XML Element Definitions . . . . . . . . . . . . . . . . . . . 36
+ 10.1. CARDDAV:addressbook XML Element . . . . . . . . . . . . . 36
+ 10.2. CARDDAV:supported-collation XML Element . . . . . . . . . 36
+ 10.3. CARDDAV:addressbook-query XML Element . . . . . . . . . . 37
+ 10.4. CARDDAV:address-data XML Element . . . . . . . . . . . . . 37
+ 10.4.1. CARDDAV:allprop XML Element . . . . . . . . . . . . . 39
+ 10.4.2. CARDDAV:prop XML Element . . . . . . . . . . . . . . . 39
+ 10.5. CARDDAV:filter XML Element . . . . . . . . . . . . . . . . 40
+ 10.5.1. CARDDAV:prop-filter XML Element . . . . . . . . . . . 40
+ 10.5.2. CARDDAV:param-filter XML Element . . . . . . . . . . . 41
+ 10.5.3. CARDDAV:is-not-defined XML Element . . . . . . . . . . 42
+ 10.5.4. CARDDAV:text-match XML Element . . . . . . . . . . . . 42
+ 10.6. CARDDAV:limit XML Element . . . . . . . . . . . . . . . . 43
+ 10.6.1. CARDDAV:nresults XML Element . . . . . . . . . . . . . 44
+ 10.7. CARDDAV:addressbook-multiget XML Element . . . . . . . . . 44
+ 11. Service Discovery via SRV Records . . . . . . . . . . . . . . 45
+ 12. Internationalization Considerations . . . . . . . . . . . . . 45
+ 13. Security Considerations . . . . . . . . . . . . . . . . . . . 45
+ 14. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 46
+ 14.1. Namespace Registration . . . . . . . . . . . . . . . . . . 46
+ 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46
+ 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 47
+ 16.1. Normative References . . . . . . . . . . . . . . . . . . . 47
+ 16.2. Informative References . . . . . . . . . . . . . . . . . . 48
+
+
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 3]
+
+RFC 6352 CardDAV August 2011
+
+
+1. Introduction and Overview
+
+ Address books containing contact information are a key component of
+ personal information management tools, such as email, calendaring and
+ scheduling, and instant messaging clients. To date several protocols
+ have been used for remote access to contact data, including the
+ Lightweight Directory Access Protocol (LDAP) [RFC4510], Internet
+ Message Support Protocol [IMSP], and Application Configuration Access
+ Protocol (ACAP) [RFC2244], together with SyncML used for
+ synchronization of such data.
+
+ WebDAV [RFC4918] offers a number of advantages as a framework or
+ basis for address book access and management. Most of these
+ advantages boil down to a significant reduction in the costs of
+ design, implementation, interoperability testing, and deployment.
+
+ The key features of address book support with WebDAV are:
+
+ 1. Ability to use multiple address books with hierarchical layout.
+
+ 2. Ability to control access to individual address books and address
+ entries as per WebDAV Access Control List (ACL) [RFC3744].
+
+ 3. Principal collections can be used to enumerate and query other
+ users on the system as per WebDAV ACL [RFC3744].
+
+ 4. Server-side searching of address data, avoiding the need for
+ clients to download an entire address book in order to do a quick
+ address 'expansion' operation.
+
+ 5. Well-defined internationalization support through WebDAV's use of
+ XML.
+
+ 6. Use of vCards [RFC2426] for well-defined address schema to
+ enhance client interoperability.
+
+ 7. Many limited clients (e.g., mobile devices) contain an HTTP stack
+ that makes implementing WebDAV much easier than other protocols.
+
+ The key disadvantage of address book support in WebDAV is:
+
+ 1. Lack of change notification. Many of the alternative protocols
+ also lack this ability. However, an extension for push
+ notifications could easily be developed.
+
+ vCard is a MIME directory profile aimed at encapsulating personal
+ addressing and contact information about people. The specification
+ of vCard was originally done by the Versit consortium, with a
+
+
+
+Daboo Standards Track [Page 4]
+
+RFC 6352 CardDAV August 2011
+
+
+ subsequent 3.0 version standardized by the IETF [RFC2426]. vCard is
+ in widespread use in email clients and mobile devices as a means of
+ encapsulating address information for transport via email or for
+ import/export and synchronization operations.
+
+ An update to vCard -- vCard v4 -- is currently being developed
+ [RFC6350] and is compatible with this specification.
+
+2. Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC2119].
+
+ The term "protected" is used in the Conformance field of property
+ definitions as defined in Section 15 of [RFC4918].
+
+ This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section
+ 3.2) as a purely notational convention. WebDAV request and response
+ bodies cannot be validated by a DTD due to the specific extensibility
+ rules defined in Section 17 of [RFC4918] and due to the fact that all
+ XML elements defined by that specification use the XML namespace name
+ "DAV:". In particular:
+
+ 1. Element names use the "DAV:" namespace.
+
+ 2. Element ordering is irrelevant unless explicitly stated.
+
+ 3. Extension elements (elements not already defined as valid child
+ elements) may be added anywhere, except when explicitly stated
+ otherwise.
+
+ 4. Extension attributes (attributes not already defined as valid for
+ this element) may be added anywhere, except when explicitly
+ stated otherwise.
+
+ The namespace "urn:ietf:params:xml:ns:carddav" is reserved for the
+ XML elements defined in this specification, its revisions, and
+ related CardDAV specifications. XML elements defined by individual
+ implementations MUST NOT use the "urn:ietf:params:xml:ns:carddav"
+ namespace, and instead should use a namespace that they control.
+
+ When XML element types in the namespaces "DAV:" and
+ "urn:ietf:params:xml:ns:carddav" are referenced in this document
+ outside of the context of an XML fragment, the strings "DAV:" and
+ "CARDDAV:" will be prefixed to the element types, respectively.
+
+
+
+
+
+Daboo Standards Track [Page 5]
+
+RFC 6352 CardDAV August 2011
+
+
+ This document inherits, and sometimes extends, DTD productions from
+ Section 14 of [RFC4918].
+
+ Also, note that some CardDAV XML element names are identical to
+ WebDAV XML element names, though their namespace differs. Care must
+ be taken not to confuse the two sets of names.
+
+3. Requirements Overview
+
+ This section lists what functionality is required of a CardDAV
+ server. To advertise support for CardDAV, a server:
+
+ o MUST support vCard v3 [RFC2426] as a media type for the address
+ object resource format;
+
+ o MUST support WebDAV Class 3 [RFC4918];
+
+ o MUST support WebDAV ACL [RFC3744];
+
+ o MUST support secure transport as defined in [RFC2818] using
+ Transport Layer Security (TLS) [RFC5246] and using the certificate
+ validation procedures described in [RFC5280];
+
+ o MUST support ETags [RFC2616] with additional requirements
+ specified in Section 6.3.2.3 of this document;
+
+ o MUST support all address book reports defined in Section 8 of this
+ document; and
+
+ o MUST advertise support on all address book collections and address
+ object resources for the address book reports in the
+ DAV:supported-report-set property, as defined in Versioning
+ Extensions to WebDAV [RFC3253].
+
+ In addition, a server:
+
+ o SHOULD support vCard v4 [RFC6350] as a media type for the address
+ object resource format;
+
+ o SHOULD support the extended MKCOL method [RFC5689] to create
+ address book collections as defined in Section 6.3.1 of this
+ document.
+
+ o SHOULD support the DAV:current-user-principal-URL property as
+ defined in [RFC5397] to give clients a fast way to locate user
+ principals.
+
+
+
+
+
+Daboo Standards Track [Page 6]
+
+RFC 6352 CardDAV August 2011
+
+
+4. Address Book Data Model
+
+ As a brief overview, a CardDAV address book is modeled as a WebDAV
+ collection with a well-defined structure; each of these address book
+ collections contains a number of resources representing address
+ objects as their direct child resources. Each resource representing
+ an address object is called an "address object resource". Each
+ address object resource and each address book collection can be
+ individually locked and have individual WebDAV properties.
+ Requirements derived from this model are provided in Sections 5.1 and
+ 5.2.
+
+4.1. Address Book Server
+
+ A CardDAV server is an address-aware engine combined with a WebDAV
+ server. The server may include address data in some parts of its URL
+ namespace and non-address data in other parts.
+
+ A WebDAV server can advertise itself as a CardDAV server if it
+ supports the functionality defined in this specification at any point
+ within the root of its repository. That might mean that address data
+ is spread throughout the repository and mixed with non-address data
+ in nearby collections (e.g., address data may be found in /lisa/
+ addressbook/ as well as in /bernard/addressbook/, and non-address
+ data in /lisa/calendars/). Or, it might mean that address data can
+ be found only in certain sections of the repository (e.g.,
+ /addressbooks/user/). Address book features are only required in the
+ repository sections that are or contain address objects. So, a
+ repository confining address data to the /carddav/ collection would
+ only need to support the CardDAV required features within that
+ collection.
+
+ The CardDAV server is the canonical location for address data and
+ state information. Clients may submit requests to change data or
+ download data. Clients may store address objects offline and attempt
+ to synchronize at a later time. Address data on the server can
+ change between the time of last synchronization and when attempting
+ an update, as address book collections may be shared and accessible
+ via multiple clients. Entity tags and locking help this work.
+
+5. Address Book Resources
+
+5.1. Address Object Resources
+
+ This specification uses vCard as the default format for address or
+ contact information being stored on the server. However, this
+ specification does allow other formats for address data provided that
+ the server advertises support for those additional formats as
+
+
+
+Daboo Standards Track [Page 7]
+
+RFC 6352 CardDAV August 2011
+
+
+ described below. The requirements in this section pertain to vCard
+ address data or formats that follow the semantics of vCard data.
+
+ Address object resources contained in address book collections MUST
+ contain a single vCard component only.
+
+ vCard components in an address book collection MUST have a UID
+ property value that MUST be unique in the scope of the address book
+ collection in which it is contained.
+
+5.1.1. Data Type Conversion
+
+ Servers might support more than one primary media type for address
+ object resources, for example, vCard v3.0 and vCard v4.0. In such
+ cases, servers have to accept all media types that they advertise via
+ the CARDDAV:supported-address-data WebDAV property (see
+ Section 6.2.2).
+
+ However, clients can use standard HTTP content negotiation behavior
+ (the Accept request header defined in Section 14.1 of [RFC2616]) to
+ request that an address object resource's data be returned in a
+ specific media type format. For example, a client merely capable of
+ handling vCard v3.0 would only want to have address object resources
+ returned in v3.0 format.
+
+ Additionally, REPORT requests, defined later in this specification,
+ allow for the return of address object resource data within an XML
+ response body. Again, the client can use content negotiation to
+ request that data be returned in a specific media type by specifying
+ appropriate attributes on the CARDDAV:address-data XML element used
+ in the request body (see Section 10.4).
+
+ In some cases, it might not be possible for a server to convert from
+ one media type to another. When that happens, the server MUST return
+ the CARDDAV:supported-address-data-conversion precondition (see
+ below) in the response body (when the failure to convert applies to
+ the entire response) or use that same precondition code in the
+ DAV:response XML element in the response for the targeted address
+ object resource when one of the REPORTs defined below is used. See
+ Section 8.7.2 for an example of this.
+
+5.1.1.1. Additional Precondition for GET
+
+ This specification creates additional preconditions for the GET
+ method.
+
+
+
+
+
+
+Daboo Standards Track [Page 8]
+
+RFC 6352 CardDAV August 2011
+
+
+ The new precondition is:
+
+ (CARDDAV:supported-address-data-conversion): The resource targeted
+ by the GET request can be converted to the media type specified in
+ the Accept request header included with the request.
+
+5.2. Address Book Collections
+
+ Address book collections appear to clients as a WebDAV collection
+ resource, identified by a URL. An address book collection MUST
+ report the DAV:collection and CARDDAV:addressbook XML elements in the
+ value of the DAV:resourcetype property. The element type declaration
+ for CARDDAV:addressbook is:
+
+ <!ELEMENT addressbook EMPTY>
+
+ An address book collection can be created through provisioning (e.g.,
+ automatically created when a user's account is provisioned), or it
+ can be created with the extended MKCOL method (see Section 6.3.1).
+ This can be used by a user to create additional address books (e.g.,
+ "soccer team members") or for users to share an address book (e.g.,
+ "sales team contacts"). However, note that this document doesn't
+ define what extra address book collections are for. Users must rely
+ on non-standard cues to find out what an address book collection is
+ for, or use the CARDDAV:addressbook-description property defined in
+ Section 6.2.1 to provide such a cue.
+
+ The following restrictions are applied to the resources within an
+ address book collection:
+
+ a. Address book collections MUST only contain address object
+ resources and collections that are not address book collections.
+ That is, the only "top-level" non-collection resources allowed in
+ an address book collection are address object resources. This
+ ensures that address book clients do not have to deal with non-
+ address data in an address book collection, though they do have
+ to distinguish between address object resources and collections
+ when using standard WebDAV techniques to examine the contents of
+ a collection.
+
+ b. Collections contained in address book collections MUST NOT
+ contain address book collections at any depth. That is,
+ "nesting" of address book collections within other address book
+ collections at any depth is not allowed. This specification does
+ not define how collections contained in an address book
+ collection are used or how they relate to any address object
+ resources contained in the address book collection.
+
+
+
+
+Daboo Standards Track [Page 9]
+
+RFC 6352 CardDAV August 2011
+
+
+ Multiple address book collections MAY be children of the same
+ collection.
+
+6. Address Book Feature
+
+6.1. Address Book Support
+
+ A server supporting the features described in this document MUST
+ include "addressbook" as a field in the DAV response header from an
+ OPTIONS request on any resource that supports any address book
+ properties, reports, or methods. A value of "addressbook" in the DAV
+ response header MUST indicate that the server supports all MUST level
+ requirements and REQUIRED features specified in this document.
+
+6.1.1. Example: Using OPTIONS for the Discovery of Support for CardDAV
+
+ >> Request <<
+
+ OPTIONS /addressbooks/users/ HTTP/1.1
+ Host: addressbook.example.com
+
+ >> Response <<
+
+ HTTP/1.1 200 OK
+ Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
+ Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
+ DAV: 1, 2, 3, access-control, addressbook
+ DAV: extended-mkcol
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Length: 0
+
+ In this example, the OPTIONS response indicates that the server
+ supports CardDAV in this namespace; therefore, the '/addressbooks/
+ users/' collection may be used as a parent for address book
+ collections as the extended MKCOL method is available and as a
+ possible target for REPORT requests for address book reports.
+
+6.2. Address Book Properties
+
+6.2.1. CARDDAV:addressbook-description Property
+
+ Name: addressbook-description
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Provides a human-readable description of the address book
+ collection.
+
+
+
+
+Daboo Standards Track [Page 10]
+
+RFC 6352 CardDAV August 2011
+
+
+ Value: Any text.
+
+ Protected: SHOULD NOT be protected so that users can specify a
+ description.
+
+ COPY/MOVE behavior: This property value SHOULD be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: This property contains a description of the address
+ book collection that is suitable for presentation to a user. The
+ xml:lang attribute can be used to add a language tag for the value
+ of this property.
+
+ Definition:
+
+ <!ELEMENT addressbook-description (#PCDATA)>
+ <!-- PCDATA value: string -->
+
+ Example:
+
+ <C:addressbook-description xml:lang="fr-CA"
+ xmlns:C="urn:ietf:params:xml:ns:carddav"
+ >Adresses de Oliver Daboo</C:addressbook-description>
+
+6.2.2. CARDDAV:supported-address-data Property
+
+ Name: supported-address-data
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies what media types are allowed for address object
+ resources in an address book collection.
+
+ Protected: MUST be protected as it indicates the level of support
+ provided by the server.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: The CARDDAV:supported-address-data property is used to
+ specify the media type supported for the address object resources
+ contained in a given address book collection (e.g., vCard version
+
+
+
+Daboo Standards Track [Page 11]
+
+RFC 6352 CardDAV August 2011
+
+
+ 3.0). Any attempt by the client to store address object resources
+ with a media type not listed in this property MUST result in an
+ error, with the CARDDAV:supported-address-data precondition
+ (Section 6.3.2.1) being violated. In the absence of this
+ property, the server MUST only accept data with the media type
+ "text/vcard" and vCard version 3.0, and clients can assume that is
+ all the server will accept.
+
+ Definition:
+
+ <!ELEMENT supported-address-data (address-data-type+)>
+
+ <!ELEMENT address-data-type EMPTY>
+ <!ATTLIST address-data-type content-type CDATA "text/vcard"
+ version CDATA "3.0">
+ <!-- content-type value: a MIME media type -->
+ <!-- version value: a version string -->
+
+ Example:
+
+ <C:supported-address-data
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <C:address-data-type content-type="text/vcard" version="3.0"/>
+ </C:supported-address-data>
+
+6.2.3. CARDDAV:max-resource-size Property
+
+ Name: max-resource-size
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Provides a numeric value indicating the maximum size in
+ octets of a resource that the server is willing to accept when an
+ address object resource is stored in an address book collection.
+
+ Value: Any text representing a numeric value.
+
+ Protected: MUST be protected as it indicates limits provided by the
+ server.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+
+
+
+
+
+Daboo Standards Track [Page 12]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:max-resource-size is used to specify a
+ numeric value that represents the maximum size in octets that the
+ server is willing to accept when an address object resource is
+ stored in an address book collection. Any attempt to store an
+ address book object resource exceeding this size MUST result in an
+ error, with the CARDDAV:max-resource-size precondition
+ (Section 6.3.2.1) being violated. In the absence of this
+ property, the client can assume that the server will allow storing
+ a resource of any reasonable size.
+
+ Definition:
+
+ <!ELEMENT max-resource-size (#PCDATA)>
+ <!-- PCDATA value: a numeric value (positive decimal integer) -->
+
+ Example:
+
+ <C:max-resource-size xmlns:C="urn:ietf:params:xml:ns:carddav"
+ >102400</C:max-resource-size>
+
+6.3. Creating Resources
+
+ Address book collections and address object resources may be created
+ by either a CardDAV client or the CardDAV server. This specification
+ defines restrictions and a data model that both clients and servers
+ MUST adhere to when manipulating such address data.
+
+6.3.1. Extended MKCOL Method
+
+ An HTTP request using the extended MKCOL method [RFC5689] can be used
+ to create a new address book collection resource. A server MAY
+ restrict address book collection creation to particular collections.
+
+ To create an address book, the client sends an extended MKCOL request
+ to the server and in the body of the request sets the
+ DAV:resourcetype property to the resource type for an address book
+ collection as defined in Section 5.2.
+
+ Support for creating address books on the server is only RECOMMENDED
+ and not REQUIRED because some address book stores only support one
+ address book per user (or principal), and those are typically pre-
+ created for each account. However, servers and clients are strongly
+ encouraged to support address book creation whenever possible to
+ allow users to create multiple address book collections to help
+ organize their data better.
+
+
+
+
+
+
+Daboo Standards Track [Page 13]
+
+RFC 6352 CardDAV August 2011
+
+
+ The DAV:displayname property can be used for a human-readable name of
+ the address book. Clients can either specify the value of the
+ DAV:displayname property in the request body of the extended MKCOL
+ request or, alternatively, issue a PROPPATCH request to change the
+ DAV:displayname property to the appropriate value immediately after
+ using the extended MKCOL request. When displaying address book
+ collections to users, clients SHOULD check the DAV:displayname
+ property and use that value as the name of the address book. In the
+ event that the DAV:displayname property is not set, the client MAY
+ use the last part of the address book collection URI as the name;
+ however, that path segment may be "opaque" and not represent any
+ meaningful human-readable text.
+
+6.3.1.1. Example - Successful MKCOL Request
+
+ This example creates an address book collection called /home/lisa/
+ addressbook/ on the server addressbook.example.com with specific
+ values for the properties DAV:resourcetype, DAV:displayname, and
+ CARDDAV:addressbook-description.
+
+ >> Request <<
+
+ MKCOL /home/lisa/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:mkcol xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:set>
+ <D:prop>
+ <D:resourcetype>
+ <D:collection/>
+ <C:addressbook/>
+ </D:resourcetype>
+ <D:displayname>Lisa's Contacts</D:displayname>
+ <C:addressbook-description xml:lang="en"
+ >My primary address book.</C:addressbook-description>
+ </D:prop>
+ </D:set>
+ </D:mkcol>
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 14]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Response <<
+
+ HTTP/1.1 201 Created
+ Cache-Control: no-cache
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:mkcol-response xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:propstat>
+ <D:prop>
+ <D:resourcetype/>
+ <D:displayname/>
+ <C:addressbook-description/>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:mkcol-response>
+
+6.3.2. Creating Address Object Resources
+
+ Clients populate address book collections with address object
+ resources. The URL for each address object resource is entirely
+ arbitrary and does not need to bear a specific relationship (but
+ might) to the address object resource's vCard properties or other
+ metadata. New address object resources MUST be created with a PUT
+ request targeted at an unmapped URI. A PUT request targeted at a
+ mapped URI updates an existing address object resource.
+
+ When servers create new resources, it's not hard for the server to
+ choose a unique URL. It's slightly tougher for clients, because a
+ client might not want to examine all resources in the collection and
+ might not want to lock the entire collection to ensure that a new one
+ isn't created with a name collision. However, there is an HTTP
+ feature to mitigate this. If the client intends to create a new
+ address resource, the client SHOULD use the HTTP header "If-None-
+ Match: *" on the PUT request. The Request-URI on the PUT request
+ MUST include the target collection, where the resource is to be
+ created, plus the name of the resource in the last path segment. The
+ "If-None-Match" header ensures that the client will not inadvertently
+ overwrite an existing resource even if the last path segment turned
+ out to already be used.
+
+
+
+
+
+
+
+Daboo Standards Track [Page 15]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Request <<
+
+ PUT /lisa/addressbook/newvcard.vcf HTTP/1.1
+ If-None-Match: *
+ Host: addressbook.example.com
+ Content-Type: text/vcard
+ Content-Length: xxx
+
+ BEGIN:VCARD
+ VERSION:3.0
+ FN:Cyrus Daboo
+ N:Daboo;Cyrus
+ ADR;TYPE=POSTAL:;2822 Email HQ;Suite 2821;RFCVille;PA;15213;USA
+ EMAIL;TYPE=INTERNET,PREF:cyrus@example.com
+ NICKNAME:me
+ NOTE:Example VCard.
+ ORG:Self Employed
+ TEL;TYPE=WORK,VOICE:412 605 0499
+ TEL;TYPE=FAX:412 605 0705
+ URL:http://www.example.com
+ UID:1234-5678-9000-1
+ END:VCARD
+
+ >> Response <<
+
+ HTTP/1.1 201 Created
+ Date: Thu, 02 Sep 2004 16:53:32 GMT
+ Content-Length: 0
+ ETag: "123456789-000-111"
+
+ The request to change an existing address object resource without
+ overwriting a change made on the server uses a specific ETag in an
+ "If-Match" header, rather than the "If-None-Match" header.
+
+ File names for vCards are commonly suffixed by ".vcf", and clients
+ may choose to use the same convention for URLs.
+
+6.3.2.1. Additional Preconditions for PUT, COPY, and MOVE
+
+ This specification creates additional preconditions for the PUT,
+ COPY, and MOVE methods. These preconditions apply:
+
+ o When a PUT operation of an address object resource into an address
+ book collection occurs.
+
+ o When a COPY or MOVE operation of an address object resource into
+ an address book collection occurs.
+
+
+
+
+Daboo Standards Track [Page 16]
+
+RFC 6352 CardDAV August 2011
+
+
+ The new preconditions are:
+
+ (CARDDAV:supported-address-data): The resource submitted in the
+ PUT request, or targeted by a COPY or MOVE request, MUST be a
+ supported media type (i.e., vCard) for address object resources.
+
+ (CARDDAV:valid-address-data): The resource submitted in the PUT
+ request, or targeted by a COPY or MOVE request, MUST be valid data
+ for the media type being specified (i.e., MUST contain valid vCard
+ data).
+
+ (CARDDAV:no-uid-conflict): The resource submitted in the PUT
+ request, or targeted by a COPY or MOVE request, MUST NOT specify a
+ vCard UID property value already in use in the targeted address
+ book collection or overwrite an existing address object resource
+ with one that has a different UID property value. Servers SHOULD
+ report the URL of the resource that is already making use of the
+ same UID property value in the DAV:href element.
+
+ <!ELEMENT no-uid-conflict (DAV:href)>
+
+ (CARDDAV:addressbook-collection-location-ok): In a COPY or MOVE
+ request, when the Request-URI is an address book collection, the
+ URI targeted by the Destination HTTP Request header MUST identify
+ a location where an address book collection can be created.
+
+ (CARDDAV:max-resource-size): The resource submitted in the PUT
+ request, or targeted by a COPY or MOVE request, MUST have a size
+ in octets less than or equal to the value of the
+ CARDDAV:max-resource-size property value (Section 6.2.3) on the
+ address book collection where the resource will be stored.
+
+6.3.2.2. Non-Standard vCard Properties and Parameters
+
+ vCard provides a "standard mechanism for doing non-standard things".
+ This extension support allows implementers to make use of non-
+ standard vCard properties and parameters whose names are prefixed
+ with the text "X-".
+
+ Servers MUST support the use of non-standard properties and
+ parameters in address object resources stored via the PUT method.
+
+ Servers may need to enforce rules for their own "private" properties
+ or parameters, so servers MAY reject any attempt by the client to
+ change those or use values for those outside of any restrictions the
+ server may have. A server SHOULD ensure that any "private"
+
+
+
+
+
+Daboo Standards Track [Page 17]
+
+RFC 6352 CardDAV August 2011
+
+
+ properties or parameters it uses follow the convention of including a
+ vendor ID in the "X-" name, as described in Section 3.8 of [RFC2426],
+ e.g., "X-ABC-PRIVATE".
+
+6.3.2.3. Address Object Resource Entity Tag
+
+ The DAV:getetag property MUST be defined and set to a strong entity
+ tag on all address object resources.
+
+ A response to a GET request targeted at an address object resource
+ MUST contain an ETag response header field indicating the current
+ value of the strong entity tag of the address object resource.
+
+ Servers SHOULD return a strong entity tag (ETag header) in a PUT
+ response when the stored address object resource is equivalent by
+ octet equality to the address object resource submitted in the body
+ of the PUT request. This allows clients to reliably use the returned
+ strong entity tag for data synchronization purposes. For instance,
+ the client can do a PROPFIND request on the stored address object
+ resource, have the DAV:getetag property returned, compare that value
+ with the strong entity tag it received on the PUT response, and know
+ that if they are equal, then the address object resource on the
+ server has not been changed.
+
+ In the case where the data stored by a server as a result of a PUT
+ request is not equivalent by octet equality to the submitted address
+ object resource, the behavior of the ETag response header is not
+ specified here, with the exception that a strong entity tag MUST NOT
+ be returned in the response. As a result, a client may need to
+ retrieve the modified address object resource (and ETag) as a basis
+ for further changes, rather than use the address object resource it
+ had sent with the PUT request.
+
+7. Address Book Access Control
+
+ CardDAV servers MUST support and adhere to the requirements of WebDAV
+ ACL [RFC3744]. WebDAV ACL provides a framework for an extensible set
+ of privileges that can be applied to WebDAV collections and ordinary
+ resources.
+
+7.1. Additional Principal Properties
+
+ This section defines additional properties for WebDAV principal
+ resources as defined in [RFC3744].
+
+
+
+
+
+
+
+Daboo Standards Track [Page 18]
+
+RFC 6352 CardDAV August 2011
+
+
+7.1.1. CARDDAV:addressbook-home-set Property
+
+ Name: addressbook-home-set
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Identifies the URL of any WebDAV collections that contain
+ address book collections owned by the associated principal
+ resource.
+
+ Protected: MAY be protected if the server has fixed locations in
+ which address books are created.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: The CARDDAV:addressbook-home-set property is meant to
+ allow users to easily find the address book collections owned by
+ the principal. Typically, users will group all the address book
+ collections that they own under a common collection. This
+ property specifies the URL of collections that are either address
+ book collections or ordinary collections that have child or
+ descendant address book collections owned by the principal.
+
+ Definition:
+
+ <!ELEMENT addressbook-home-set (DAV:href*)>
+
+ Example:
+
+ <C:addressbook-home-set xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:href>/bernard/addresses/</D:href>
+ </C:addressbook-home-set>
+
+7.1.2. CARDDAV:principal-address Property
+
+ Name: principal-address
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Identifies the URL of an address object resource that
+ corresponds to the user represented by the principal.
+
+
+
+
+
+Daboo Standards Track [Page 19]
+
+RFC 6352 CardDAV August 2011
+
+
+ Protected: MAY be protected if the server provides a fixed location
+ for principal addresses.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: The CARDDAV:principal-address property is meant to
+ allow users to easily find contact information for users
+ represented by principals on the system. This property specifies
+ the URL of the resource containing the corresponding contact
+ information. The resource could be an address object resource in
+ an address book collection, or it could be a resource in a
+ "regular" collection.
+
+ Definition:
+
+ <!ELEMENT principal-address (DAV:href)>
+
+ Example:
+
+ <C:principal-address xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:href>/system/cyrus.vcf</D:href>
+ </C:principal-address>
+
+8. Address Book Reports
+
+ This section defines the reports that CardDAV servers MUST support on
+ address book collections and address object resources.
+
+ CardDAV servers MUST advertise support for these reports on all
+ address book collections and address object resources with the
+ DAV:supported-report-set property defined in Section 3.1.5 of
+ [RFC3253]. CardDAV servers MAY also advertise support for these
+ reports on ordinary collections.
+
+ Some of these reports allow address data (from possibly multiple
+ resources) to be returned.
+
+8.1. REPORT Method
+
+ The REPORT method (defined in Section 3.6 of [RFC3253]) provides an
+ extensible mechanism for obtaining information about a resource.
+ Unlike the PROPFIND method, which returns the value of one or more
+ named properties, the REPORT method can involve more complex
+
+
+
+Daboo Standards Track [Page 20]
+
+RFC 6352 CardDAV August 2011
+
+
+ processing. REPORT is valuable in cases where the server has access
+ to all of the information needed to perform the complex request (such
+ as a query), and where it would require multiple requests for the
+ client to retrieve the information needed to perform the same
+ request.
+
+ A server that supports this specification MUST support the
+ DAV:expand-property report (defined in Section 3.8 of [RFC3253]).
+
+8.2. Ordinary Collections
+
+ Servers MAY support the reports defined in this document on ordinary
+ collections (collections that are not address book collections) in
+ addition to address book collections or address object resources. In
+ computing responses to the reports on ordinary collections, servers
+ MUST only consider address object resources contained in address book
+ collections that are targeted by the REPORT based on the value of the
+ Depth request header.
+
+8.3. Searching Text: Collations
+
+ Some of the reports defined in this section do text matches of
+ character strings provided by the client and compared to stored
+ address data. Since vCard data is by default encoded in the UTF-8
+ charset and may include characters outside of the US-ASCII charset
+ range in some property and parameter values, there is a need to
+ ensure that text matching follows well-defined rules.
+
+ To deal with this, this specification makes use of the IANA Collation
+ Registry defined in [RFC4790] to specify collations that may be used
+ to carry out the text comparison operations with a well-defined rule.
+
+ Collations supported by the server MUST support "equality" and
+ "substring" match operations as per [RFC4790], Section 4.2, including
+ the "prefix" and "suffix" options for "substring" matching. CardDAV
+ uses these match options for "equals", "contains", "starts-with", and
+ "ends-with" match operations.
+
+ CardDAV servers are REQUIRED to support the "i;ascii-casemap"
+ [RFC4790] and "i;unicode-casemap" [RFC5051] collations and MAY
+ support other collations.
+
+ Servers MUST advertise the set of collations that they support via
+ the CARDDAV:supported-collation-set property defined on any resource
+ that supports reports that use collations.
+
+
+
+
+
+
+Daboo Standards Track [Page 21]
+
+RFC 6352 CardDAV August 2011
+
+
+ In the absence of a collation explicitly specified by the client, or
+ if the client specifies the "default" collation identifier (as
+ defined in [RFC4790], Section 3.1), the server MUST default to using
+ "i;unicode-casemap" as the collation.
+
+ Wildcards (as defined in [RFC4790], Section 3.2) MUST NOT be used in
+ the collation identifier.
+
+ If the client chooses a collation not supported by the server, the
+ server MUST respond with a CARDDAV:supported-collation precondition
+ error response.
+
+8.3.1. CARDDAV:supported-collation-set Property
+
+ Name: supported-collation-set
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Identifies the set of collations supported by the server
+ for text matching operations.
+
+ Protected: MUST be protected as it indicates support provided by the
+ server.
+
+ COPY/MOVE behavior: This property value MUST be preserved in COPY
+ and MOVE operations.
+
+ allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop
+ request.
+
+ Description: The CARDDAV:supported-collation-set property contains
+ two or more CARDDAV:supported-collation elements that specify the
+ identifiers of the collations supported by the server.
+
+ Definition:
+
+ <!ELEMENT supported-collation-set (
+ supported-collation
+ supported-collation
+ supported-collation*)>
+ <!-- Both "i;ascii-casemap" and "i;unicode-casemap"
+ will be present -->
+
+ <!ELEMENT supported-collation (#PCDATA)>
+
+
+
+
+
+
+
+Daboo Standards Track [Page 22]
+
+RFC 6352 CardDAV August 2011
+
+
+ Example:
+
+ <C:supported-collation-set
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <C:supported-collation>i;ascii-casemap</C:supported-collation>
+ <C:supported-collation>i;octet</C:supported-collation>
+ <C:supported-collation>i;unicode-casemap</C:supported-collation>
+ </C:supported-collation-set>
+
+8.4. Partial Retrieval
+
+ Some address book reports defined in this document allow partial
+ retrieval of address object resources. A CardDAV client can specify
+ what information to return in the body of an address book REPORT
+ request.
+
+ A CardDAV client can request particular WebDAV property values, all
+ WebDAV property values, or a list of the names of the resource's
+ WebDAV properties. A CardDAV client can also request address data to
+ be returned and whether all vCard properties should be returned or
+ only particular ones. See CARDDAV:address-data in Section 10.4.
+
+8.5. Non-Standard Properties and Parameters
+
+ Servers MUST support the use of non-standard vCard property or
+ parameter names in the CARDDAV:address-data XML element in address
+ book REPORT requests to allow clients to request that non-standard
+ properties and parameters be returned in the address data provided in
+ the response.
+
+ Servers MAY support the use of non-standard vCard property or
+ parameter names in the CARDDAV:prop-filter and CARDDAV:param-filter
+ XML elements specified in the CARDDAV:filter XML element of address
+ book REPORT requests.
+
+ Servers MUST fail with the CARDDAV:supported-filter precondition if
+ an address book REPORT request uses a CARDDAV:prop-filter or
+ CARDDAV:param-filter XML element that makes reference to a non-
+ standard vCard property or parameter name on which the server does
+ not support queries.
+
+8.6. CARDDAV:addressbook-query Report
+
+ The CARDDAV:addressbook-query REPORT performs a search for all
+ address object resources that match a specified filter. The response
+ of this report will contain all the WebDAV properties and address
+ object resource data specified in the request. In the case of the
+
+
+
+
+Daboo Standards Track [Page 23]
+
+RFC 6352 CardDAV August 2011
+
+
+ CARDDAV:address-data XML element, one can explicitly specify the
+ vCard properties that should be returned in the address object
+ resource data that matches the filter.
+
+ The format of this report is modeled on the PROPFIND method. The
+ request and response bodies of the CARDDAV:addressbook-query report
+ use XML elements that are also used by PROPFIND. In particular, the
+ request can include XML elements to request WebDAV properties to be
+ returned. When that occurs, the response should follow the same
+ behavior as PROPFIND with respect to the DAV:multistatus response
+ elements used to return specific WebDAV property results. For
+ instance, a request to retrieve the value of a WebDAV property that
+ does not exist is an error and MUST be noted with a response XML
+ element that contains a 404 (Not Found) status value.
+
+ Support for the CARDDAV:addressbook-query REPORT is REQUIRED.
+
+ Marshalling:
+
+ The request body MUST be a CARDDAV:addressbook-query XML element
+ as defined in Section 10.3.
+
+ The request MUST include a Depth header. The scope of the query
+ is determined by the value of the Depth header. For example, to
+ query all address object resources in an address book collection,
+ the REPORT would use the address book collection as the Request-
+ URI and specify a Depth of 1 or infinity.
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element (i.e., the response uses the same
+ format as the response for PROPFIND). In the case where there are
+ no response elements, the returned DAV:multistatus XML element is
+ empty.
+
+ The response body for a successful CARDDAV:addressbook-query
+ REPORT request MUST contain a DAV:response element for each
+ address object that matched the search filter. Address data is
+ returned in the CARDDAV:address-data XML element inside the
+ DAV:propstat XML element.
+
+ Preconditions:
+
+ (CARDDAV:supported-address-data): The attributes "content-type"
+ and "version" of the CARDDAV:address-data XML element (see
+ Section 10.4) specify a media type supported by the server for
+ address object resources.
+
+
+
+
+
+Daboo Standards Track [Page 24]
+
+RFC 6352 CardDAV August 2011
+
+
+ (CARDDAV:supported-filter): The CARDDAV:prop-filter (see
+ Section 10.5.1) and CARDDAV:param-filter (see Section 10.5.2) XML
+ elements used in the CARDDAV:filter XML element (see Section 10.5)
+ in the REPORT request only make reference to vCard properties and
+ parameters for which queries are supported by the server. That
+ is, if the CARDDAV:filter element attempts to reference an
+ unsupported vCard property or parameter, this precondition is
+ violated. A server SHOULD report the CARDDAV:prop-filter or
+ CARDDAV:param-filter for which it does not provide support.
+
+ <!ELEMENT supported-filter (prop-filter*,
+ param-filter*)>
+
+ (CARDDAV:supported-collation): Any XML attribute specifying a
+ collation MUST specify a collation supported by the server as
+ described in Section 8.3.
+
+ Postconditions:
+
+ (DAV:number-of-matches-within-limits): The number of matching
+ address object resources must fall within server-specific,
+ predefined limits. For example, this condition might be triggered
+ if a search specification would cause the return of an extremely
+ large number of responses.
+
+8.6.1. Limiting Results
+
+ A client can limit the number of results returned by the server
+ through use of the CARDDAV:limit element in the request body. This
+ is useful when clients are only interested in a few matches or only
+ have limited space to display results to users and thus don't need
+ the overhead of receiving more than that. When the results are
+ truncated by the server, the server MUST follow the rules below for
+ indicating a result set truncation to the client.
+
+8.6.2. Truncation of Results
+
+ A server MAY limit the number of resources in a response, for
+ example, to limit the amount of work expended in processing a query,
+ or as the result of an explicit limit set by the client. If the
+ result set is truncated because of such a limit, the response MUST
+ use status code 207 (Multi-Status), return a DAV:multistatus response
+ body, and indicate a status of 507 (Insufficient Storage) for the
+ Request-URI. That DAV:response element SHOULD include a DAV:error
+ element with the DAV:number-of-matches-within-limits precondition, as
+ defined in [RFC3744], Section 9.2.
+
+
+
+
+
+Daboo Standards Track [Page 25]
+
+RFC 6352 CardDAV August 2011
+
+
+ The server SHOULD also include the partial results in additional
+ DAV:response elements. If a client-requested limit is being applied,
+ the 507 response for the Request-URI MUST NOT be included in
+ calculating the limit (e.g., if the client requests that only a
+ single result be returned, and multiple matches are present, then the
+ DAV:multistatus response will include one DAV:response for the
+ matching resource and one DAV:response for the 507 status on the
+ Request-URI).
+
+8.6.3. Example: Partial Retrieval of vCards Matching NICKNAME
+
+ In this example, the client requests that the server search for
+ address object resources that contain a NICKNAME property whose value
+ equals some specific text and return specific vCard properties for
+ those vCards found. In addition, the DAV:getetag property is also
+ requested and returned as part of the response.
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-query xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:prop>
+ <D:getetag/>
+ <C:address-data>
+ <C:prop name="VERSION"/>
+ <C:prop name="UID"/>
+ <C:prop name="NICKNAME"/>
+ <C:prop name="EMAIL"/>
+ <C:prop name="FN"/>
+ </C:address-data>
+ </D:prop>
+ <C:filter>
+ <C:prop-filter name="NICKNAME">
+ <C:text-match collation="i;unicode-casemap"
+ match-type="equals"
+ >me</C:text-match>
+ </C:prop-filter>
+ </C:filter>
+ </C:addressbook-query>
+
+
+
+
+
+Daboo Standards Track [Page 26]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/v102.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fb"</D:getetag>
+ <C:address-data>BEGIN:VCARD
+ VERSION:3.0
+ NICKNAME:me
+ UID:34222-232@example.com
+ FN:Cyrus Daboo
+ EMAIL:daboo@example.com
+ END:VCARD
+ </C:address-data>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+8.6.4. Example: Partial Retrieval of vCards Matching a Full Name or
+ Email Address
+
+ In this example, the client requests that the server search for
+ address object resources that contain a FN property whose value
+ contains some specific text or that contain an EMAIL property whose
+ value contains other text and return specific vCard properties for
+ those vCards found. In addition, the DAV:getetag property is also
+ requested and returned as part of the response.
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+
+
+
+
+Daboo Standards Track [Page 27]
+
+RFC 6352 CardDAV August 2011
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-query xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:prop>
+ <D:getetag/>
+ <C:address-data>
+ <C:prop name="VERSION"/>
+ <C:prop name="UID"/>
+ <C:prop name="NICKNAME"/>
+ <C:prop name="EMAIL"/>
+ <C:prop name="FN"/>
+ </C:address-data>
+ </D:prop>
+ <C:filter test="anyof">
+ <C:prop-filter name="FN">
+ <C:text-match collation="i;unicode-casemap"
+ match-type="contains"
+ >daboo</C:text-match>
+ </C:prop-filter>
+ <C:prop-filter name="EMAIL">
+ <C:text-match collation="i;unicode-casemap"
+ match-type="contains"
+ >daboo</C:text-match>
+ </C:prop-filter>
+ </C:filter>
+ </C:addressbook-query>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/v102.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fb"</D:getetag>
+ <C:address-data>BEGIN:VCARD
+ VERSION:3.0
+ NICKNAME:me
+ UID:34222-232@example.com
+ FN:David Boo
+ EMAIL:daboo@example.com
+
+
+
+Daboo Standards Track [Page 28]
+
+RFC 6352 CardDAV August 2011
+
+
+ END:VCARD
+ </C:address-data>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/bernard/addressbook/v104.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fc"</D:getetag>
+ <C:address-data>BEGIN:VCARD
+ VERSION:3.0
+ NICKNAME:oliver
+ UID:34222-23222@example.com
+ FN:Oliver Daboo
+ EMAIL:oliver@example.com
+ END:VCARD
+ </C:address-data>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+8.6.5. Example: Truncated Results
+
+ In this example, the client requests that the server search for
+ address object resources that contain a FN property whose value
+ contains some specific text and return the DAV:getetag property for
+ two results only. The server response includes a 507 status for the
+ Request-URI indicating that there were more than two resources that
+ matched the query, but that the server truncated the result set as
+ requested by the client.
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-query xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+
+
+
+
+
+Daboo Standards Track [Page 29]
+
+RFC 6352 CardDAV August 2011
+
+
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ <C:filter test="anyof">
+ <C:prop-filter name="FN">
+ <C:text-match collation="i;unicode-casemap"
+ match-type="contains"
+ >daboo</C:text-match>
+ </C:prop-filter>
+ </C:filter>
+ <C:limit>
+ <C:nresults>2</C:nresults>
+ </C:limit>
+ </C:addressbook-query>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/</D:href>
+ <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
+ <D:error><D:number-of-matches-within-limits/></D:error>
+ <D:responsedescription xml:lang="en">
+ Only two matching records were returned
+ </D:responsedescription>
+ </D:response>
+ <D:response>
+ <D:href>/home/bernard/addressbook/v102.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fb"</D:getetag>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/bernard/addressbook/v104.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fc"</D:getetag>
+ </D:prop>
+
+
+
+Daboo Standards Track [Page 30]
+
+RFC 6352 CardDAV August 2011
+
+
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+8.7. CARDDAV:addressbook-multiget Report
+
+ The CARDDAV:addressbook-multiget REPORT is used to retrieve specific
+ address object resources from within a collection, if the Request-URI
+ is a collection, or to retrieve a specific address object resource,
+ if the Request-URI is an address object resource. This report is
+ similar to the CARDDAV:addressbook-query REPORT (see Section 8.6),
+ except that it takes a list of DAV:href elements instead of a
+ CARDDAV:filter element to determine which address object resources to
+ return.
+
+ Support for the addressbook-multiget REPORT is REQUIRED.
+
+ Marshalling:
+
+ The request body MUST be a CARDDAV:addressbook-multiget XML
+ element (see Section 10.7), which MUST contain at least one
+ DAV:href XML element and one optional CARDDAV:address-data element
+ as defined in Section 10.4. If DAV:href elements are present, the
+ scope of the request is the set of resources identified by these
+ elements, which all need to be members (not necessarily internal
+ members) of the resource identified by the Request-URI.
+ Otherwise, the scope is the resource identified by the Request-URI
+ itself.
+
+ The request MUST include a Depth: 0 header; however, the actual
+ scope of the REPORT is determined as described above.
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element.
+
+ The response body for a successful CARDDAV:addressbook-multiget
+ REPORT request MUST contain a DAV:response element for each
+ address object resource referenced by the provided set of DAV:href
+ elements. Address data is returned in the CARDDAV:address-data
+ element inside the DAV:prop element.
+
+ In the case of an error accessing any of the provided DAV:href
+ resources, the server MUST return the appropriate error status
+ code in the DAV:status element of the corresponding DAV:response
+ element.
+
+
+
+
+
+Daboo Standards Track [Page 31]
+
+RFC 6352 CardDAV August 2011
+
+
+ Preconditions:
+
+ (CARDDAV:supported-address-data): The attributes "content-type"
+ and "version" of the CARDDAV:address-data XML elements (see
+ Section 10.4) specify a media type supported by the server for
+ address object resources.
+
+ Postconditions:
+
+ None.
+
+8.7.1. Example: CARDDAV:addressbook-multiget Report
+
+ In this example, the client requests the server to return specific
+ vCard properties of the address components referenced by specific
+ URIs. In addition, the DAV:getetag property is also requested and
+ returned as part of the response. Note that, in this example, the
+ resource at
+ http://addressbook.example.com/home/bernard/addressbook/vcf1.vcf does
+ not exist, resulting in an error status response.
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-multiget xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:prop>
+ <D:getetag/>
+ <C:address-data>
+ <C:prop name="VERSION"/>
+ <C:prop name="UID"/>
+ <C:prop name="NICKNAME"/>
+ <C:prop name="EMAIL"/>
+ <C:prop name="FN"/>
+ </C:address-data>
+ </D:prop>
+ <D:href>/home/bernard/addressbook/vcf102.vcf</D:href>
+ <D:href>/home/bernard/addressbook/vcf1.vcf</D:href>
+ </C:addressbook-multiget>
+
+
+
+
+
+
+Daboo Standards Track [Page 32]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/vcf102.vcf</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag>"23ba4d-ff11fb"</D:getetag>
+ <C:address-data>BEGIN:VCARD
+ VERSION:3.0
+ NICKNAME:me
+ UID:34222-232@example.com
+ FN:Cyrus Daboo
+ EMAIL:daboo@example.com
+ END:VCARD
+ </C:address-data>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/bernard/addressbook/vcf1.vcf</D:href>
+ <D:status>HTTP/1.1 404 Resource not found</D:status>
+ </D:response>
+ </D:multistatus>
+
+8.7.2. Example: CARDDAV:addressbook-multiget Report
+
+ In this example, the client requests the server to return vCard v4.0
+ data of the address components referenced by specific URIs. In
+ addition, the DAV:getetag property is also requested and returned as
+ part of the response. Note that, in this example, the resource at
+ http://addressbook.example.com/home/bernard/addressbook/vcf3.vcf
+ exists but in a media type format that the server is unable to
+ convert, resulting in an error status response.
+
+
+
+
+
+
+
+
+
+Daboo Standards Track [Page 33]
+
+RFC 6352 CardDAV August 2011
+
+
+ >> Request <<
+
+ REPORT /home/bernard/addressbook/ HTTP/1.1
+ Host: addressbook.example.com
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <C:addressbook-multiget xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:prop>
+ <D:getetag/>
+ <C:address-data content-type='text/vcard' version='4.0'/>
+ </D:prop>
+ <D:href>/home/bernard/addressbook/vcf3.vcf</D:href>
+ </C:addressbook-multiget>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Date: Sat, 11 Nov 2006 09:32:12 GMT
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:C="urn:ietf:params:xml:ns:carddav">
+ <D:response>
+ <D:href>/home/bernard/addressbook/vcf3.vcf</D:href>
+ <D:status>HTTP/1.1 415 Unsupported Media Type</D:status>
+ <D:error><C:supported-address-data-conversion/></D:error>
+ <D:responsedescription>Unable to convert from vCard v3.0
+ to vCard v4.0</D:responsedescription>
+ </D:response>
+ </D:multistatus>
+
+9. Client Guidelines
+
+9.1. Restrict the Properties Returned
+
+ Clients may not need all the properties in a vCard object when
+ presenting information to the user, or looking up specific items for
+ their email address, for example. Since some property data can be
+ large (e.g., PHOTO or SOUND with in-line content) clients can choose
+ to ignore those by only requesting the specific items it knows it
+ will use, through use of the CARDDAV:address-data XML element in the
+ relevant reports.
+
+
+
+Daboo Standards Track [Page 34]
+
+RFC 6352 CardDAV August 2011
+
+
+ However, if a client needs to make a change to a vCard, it can only
+ change the entire vCard data via a PUT request. There is no way to
+ incrementally make a change to a set of properties within a vCard
+ object resource. As a result, the client will have to cache the
+ entire set of properties on a resource that is being changed.
+
+9.2. Avoiding Lost Updates
+
+ When resources are accessed by multiple clients, the possibility of
+ clients overwriting each other's changes exists. To alleviate this,
+ clients SHOULD use the If-Match request header on PUT requests with
+ the ETag of the previously retrieved resource data to check whether
+ the resource was modified since it was previously retrieved. If a
+ precondition failure occurs, clients need to reload the resource and
+ go through their own merge or conflict resolution process before
+ writing back the data (again using the If-Match check).
+
+9.3. Client Configuration
+
+ When CardDAV clients need to be configured, the key piece of
+ information that they require is the principal-URL of the user whose
+ address book information is desired. Servers SHOULD support the
+ DAV:current-user-principal-URL property as defined in [RFC5397] to
+ give clients a fast way to locate user principals.
+
+ Given support for SRV records (Section 11) and DAV:current-user-
+ principal-URL [RFC5397], users only need enter a user identifier,
+ host name, and password to configure their client. The client would
+ take the host name and do an SRV lookup to locate the CardDAV server,
+ then execute an authenticated PROPFIND on the root/resource looking
+ for the DAV:current-user-principal-URL property. The value returned
+ gives the client direct access to the user's principal-URL and from
+ there all the related CardDAV properties needed to locate address
+ books.
+
+9.4. Finding Other Users' Address Books
+
+ For use cases of address book sharing, one might wish to find the
+ address book belonging to another user. To find other users' address
+ books on the same server, the DAV:principal-property-search REPORT
+ [RFC3744] can be used to search principals for matching properties
+ and return specified properties for the matching principal resources.
+ To search for an address book owned by a user named "Laurie", the
+ REPORT request body would look like this:
+
+
+
+
+
+
+
+Daboo Standards Track [Page 35]
+
+RFC 6352 CardDAV August 2011
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:principal-property-search xmlns:D="DAV:">
+ <D:property-search>
+ <D:prop>
+ <D:displayname/>
+ </D:prop>
+ <D:match>Laurie</D:match>
+ </D:property-search>
+ <D:prop>
+ <C:addressbook-home-set
+ xmlns:C="urn:ietf:params:xml:ns:carddav"/>
+ <D:displayname/>
+ </D:prop>
+ </D:principal-property-search>
+
+ The server performs a case-sensitive or caseless search for a
+ matching string subset of "Laurie" within the DAV:displayname
+ property. Thus, the server might return "Laurie Dusseault", "Laurier
+ Desruisseaux", or "Wilfrid Laurier" all as matching DAV:displayname
+ values, and the address books for each of these.
+
+10. XML Element Definitions
+
+10.1. CARDDAV:addressbook XML Element
+
+ Name: addressbook
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies the resource type of an address book collection.
+
+ Description: See Section 5.2.
+
+ Definition:
+
+ <!ELEMENT addressbook EMPTY>
+
+10.2. CARDDAV:supported-collation XML Element
+
+ Name: supported-collation
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Identifies a single collation via its collation identifier
+ as defined by [RFC4790].
+
+ Description: The CARDDAV:supported-collation contains the text of a
+ collation identifier as described in Section 8.3.1.
+
+
+
+Daboo Standards Track [Page 36]
+
+RFC 6352 CardDAV August 2011
+
+
+ Definition:
+
+ <!ELEMENT supported-collation (#PCDATA)>
+ <!-- PCDATA value: collation identifier -->
+
+10.3. CARDDAV:addressbook-query XML Element
+
+ Name: addressbook-query
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Defines a report for querying address book data
+
+ Description: See Section 8.6.
+
+ Definition:
+
+ <!ELEMENT addressbook-query ((DAV:allprop |
+ DAV:propname |
+ DAV:prop)?, filter, limit?)>
+
+10.4. CARDDAV:address-data XML Element
+
+ Name: address-data
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies one of the following:
+
+ 1. The parts of an address object resource that should be
+ returned by a given address book REPORT request, and the media
+ type and version for the returned data; or
+
+ 2. The content of an address object resource in a response to an
+ address book REPORT request.
+
+ Description: When used in an address book REPORT request, the
+ CARDDAV:address-data XML element specifies which parts of address
+ object resources need to be returned in the response. If the
+ CARDDAV:address-data XML element doesn't contain any CARDDAV:prop
+ elements, address object resources will be returned in their
+ entirety. Additionally, a media type and version can be specified
+ to request that the server return the data in that format if
+ possible.
+
+ Finally, when used in an address book REPORT response, the
+ CARDDAV:address-data XML element specifies the content of an
+ address object resource. Given that XML parsers normalize the
+
+
+
+Daboo Standards Track [Page 37]
+
+RFC 6352 CardDAV August 2011
+
+
+ two-character sequence CRLF (US-ASCII decimal 13 and US-ASCII
+ decimal 10) to a single LF character (US-ASCII decimal 10), the CR
+ character (US-ASCII decimal 13) MAY be omitted in address object
+ resources specified in the CARDDAV:address-data XML element.
+ Furthermore, address object resources specified in the
+ CARDDAV:address-data XML element MAY be invalid per their media
+ type specification if the CARDDAV:address-data XML element part of
+ the address book REPORT request did not specify required vCard
+ properties (e.g., UID, etc.) or specified a CARDDAV:prop XML
+ element with the "novalue" attribute set to "yes".
+
+ Note: The CARDDAV:address-data XML element is specified in requests
+ and responses inside the DAV:prop XML element as if it were a
+ WebDAV property. However, the CARDDAV:address-data XML element is
+ not a WebDAV property and as such it is not returned in PROPFIND
+ responses nor used in PROPPATCH requests.
+
+ Note: The address data embedded within the CARDDAV:address-data XML
+ element MUST follow the standard XML character data encoding
+ rules, including use of &lt;, &gt;, &amp; etc., entity encoding or
+ the use of a <![CDATA[ ... ]]> construct. In the latter case, the
+ vCard data cannot contain the character sequence "]]>", which is
+ the end delimiter for the CDATA section.
+
+ Definition:
+
+ <!ELEMENT address-data (allprop | prop*)>
+
+ when nested in the DAV:prop XML element in an address book
+ REPORT request to specify which parts of address object
+ resources should be returned in the response;
+
+ <!ELEMENT address-data (#PCDATA)>
+ <!-- PCDATA value: address data -->
+
+ when nested in the DAV:prop XML element in an address book
+ REPORT response to specify the content of a returned
+ address object resource.
+
+ <!ATTLIST address-data content-type CDATA "text/vcard"
+ version CDATA "3.0">
+ <!-- content-type value: a MIME media type -->
+ <!-- version value: a version string -->
+
+ attributes can be used on each variant of the
+ CALDAV:address-data XML element.
+
+
+
+
+
+Daboo Standards Track [Page 38]
+
+RFC 6352 CardDAV August 2011
+
+
+10.4.1. CARDDAV:allprop XML Element
+
+ Name: allprop
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies that all vCard properties shall be returned.
+
+ Description: This element can be used when the client wants all
+ vCard properties of components returned by a report.
+
+ Definition:
+
+ <!ELEMENT allprop EMPTY>
+
+ Note: The CARDDAV:allprop element defined here has the same name as
+ the DAV:allprop element defined in WebDAV. However, the
+ CARDDAV:allprop element defined here uses the
+ "urn:ietf:params:xml:ns:carddav" namespace, as opposed to the "DAV:"
+ namespace used for the DAV:allprop element defined in WebDAV.
+
+10.4.2. CARDDAV:prop XML Element
+
+ Name: prop
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Defines which vCard properties to return in the response.
+
+ Description: The "name" attribute specifies the name of the vCard
+ property to return (e.g., "NICKNAME"). The "novalue" attribute
+ can be used by clients to request that the actual value of the
+ property not be returned (if the "novalue" attribute is set to
+ "yes"). In that case, the server will return just the vCard
+ property name and any vCard parameters and a trailing ":" without
+ the subsequent value data.
+
+ vCard allows a "group" prefix to appear before a property name in
+ the vCard data. When the "name" attribute does not specify a
+ group prefix, it MUST match properties in the vCard data without a
+ group prefix or with any group prefix. When the "name" attribute
+ includes a group prefix, it MUST match properties that have
+ exactly the same group prefix and name. For example, a "name" set
+ to "TEL" will match "TEL", "X-ABC.TEL", and "X-ABC-1.TEL" vCard
+ properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL"
+ vCard property only; it will not match "TEL" or "X-ABC-1.TEL".
+
+
+
+
+
+Daboo Standards Track [Page 39]
+
+RFC 6352 CardDAV August 2011
+
+
+ Definition:
+
+ <!ELEMENT prop EMPTY>
+
+ <!ATTLIST prop name CDATA #REQUIRED
+ novalue (yes | no) "no">
+ <!-- name value: a vCard property name -->
+ <!-- novalue value: "yes" or "no" -->
+
+ Note: The CARDDAV:prop element defined here has the same name as the
+ DAV:prop element defined in WebDAV. However, the CARDDAV:prop
+ element defined here uses the "urn:ietf:params:xml:ns:carddav"
+ namespace, as opposed to the "DAV:" namespace used for the DAV:prop
+ element defined in WebDAV.
+
+10.5. CARDDAV:filter XML Element
+
+ Name: filter
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Determines which matching objects are returned.
+
+ Description: The "filter" element specifies the search filter used
+ to match address objects that should be returned by a report. The
+ "test" attribute specifies whether any (logical OR) or all
+ (logical AND) of the prop-filter tests need to match in order for
+ the overall filter to match.
+
+ Definition:
+
+ <!ELEMENT filter (prop-filter*)>
+
+ <!ATTLIST filter test (anyof | allof) "anyof">
+ <!-- test value:
+ anyof logical OR for prop-filter matches
+ allof logical AND for prop-filter matches -->
+
+10.5.1. CARDDAV:prop-filter XML Element
+
+ Name: prop-filter
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Limits the search to specific vCard properties.
+
+
+
+
+
+
+Daboo Standards Track [Page 40]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:prop-filter XML element specifies search
+ criteria on a specific vCard property (e.g., "NICKNAME"). An
+ address object is said to match a CARDDAV:prop-filter if:
+
+ * A vCard property of the type specified by the "name" attribute
+ exists, and the CARDDAV:prop-filter is empty, or it matches any
+ specified CARDDAV:text-match or CARDDAV:param-filter
+ conditions. The "test" attribute specifies whether any
+ (logical OR) or all (logical AND) of the text-filter and param-
+ filter tests need to match in order for the overall filter to
+ match.
+
+ or:
+
+ * A vCard property of the type specified by the "name" attribute
+ does not exist, and the CARDDAV:is-not-defined element is
+ specified.
+
+ vCard allows a "group" prefix to appear before a property name in
+ the vCard data. When the "name" attribute does not specify a
+ group prefix, it MUST match properties in the vCard data without a
+ group prefix or with any group prefix. When the "name" attribute
+ includes a group prefix, it MUST match properties that have
+ exactly the same group prefix and name. For example, a "name" set
+ to "TEL" will match "TEL", "X-ABC.TEL", "X-ABC-1.TEL" vCard
+ properties. A "name" set to "X-ABC.TEL" will match an "X-ABC.TEL"
+ vCard property only, it will not match "TEL" or "X-ABC-1.TEL".
+
+ Definition:
+
+ <!ELEMENT prop-filter (is-not-defined |
+ (text-match*, param-filter*))>
+
+ <!ATTLIST prop-filter name CDATA #REQUIRED
+ test (anyof | allof) "anyof">
+ <!-- name value: a vCard property name (e.g., "NICKNAME")
+ test value:
+ anyof logical OR for text-match/param-filter matches
+ allof logical AND for text-match/param-filter matches -->
+
+10.5.2. CARDDAV:param-filter XML Element
+
+ Name: param-filter
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Limits the search to specific parameter values.
+
+
+
+
+Daboo Standards Track [Page 41]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:param-filter XML element specifies search
+ criteria on a specific vCard property parameter (e.g., TYPE) in
+ the scope of a given CARDDAV:prop-filter. A vCard property is
+ said to match a CARDDAV:param-filter if:
+
+ * A parameter of the type specified by the "name" attribute
+ exists, and the CARDDAV:param-filter is empty, or it matches
+ the CARDDAV:text-match conditions if specified.
+
+ or:
+
+ * A parameter of the type specified by the "name" attribute does
+ not exist, and the CARDDAV:is-not-defined element is specified.
+
+ Definition:
+
+ <!ELEMENT param-filter (is-not-defined | text-match)?>
+
+ <!ATTLIST param-filter name CDATA #REQUIRED>
+ <!-- name value: a property parameter name (e.g., "TYPE") -->
+
+10.5.3. CARDDAV:is-not-defined XML Element
+
+ Name: is-not-defined
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies that a match should occur if the enclosing vCard
+ property or parameter does not exist.
+
+ Description: The CARDDAV:is-not-defined XML element specifies that a
+ match occurs if the enclosing vCard property or parameter value
+ specified in an address book REPORT request does not exist in the
+ address data being tested.
+
+ Definition:
+
+ <!ELEMENT is-not-defined EMPTY>
+
+10.5.4. CARDDAV:text-match XML Element
+
+ Name: text-match
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies a substring match on a vCard property or
+ parameter value.
+
+
+
+
+Daboo Standards Track [Page 42]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:text-match XML element specifies text used
+ for a substring match against the vCard property or parameter
+ value specified in an address book REPORT request.
+
+ The "collation" attribute is used to select the collation that the
+ server MUST use for character string matching. In the absence of
+ this attribute, the server MUST use the "i;unicode-casemap"
+ collation.
+
+ The "negate-condition" attribute is used to indicate that this
+ test returns a match if the text matches, when the attribute value
+ is set to "no", or return a match if the text does not match, if
+ the attribute value is set to "yes". For example, this can be
+ used to match components with a CATEGORIES property not set to
+ PERSON.
+
+ The "match-type" attribute is used to indicate the type of match
+ operation to use. Possible choices are:
+
+ "equals" - an exact match to the target string
+
+ "contains" - a substring match, matching anywhere within the
+ target string
+
+ "starts-with" - a substring match, matching only at the start
+ of the target string
+
+ "ends-with" - a substring match, matching only at the end of
+ the target string
+
+ Definition:
+
+ <!ELEMENT text-match (#PCDATA)>
+ <!-- PCDATA value: string -->
+
+ <!ATTLIST text-match
+ collation CDATA "i;unicode-casemap"
+ negate-condition (yes | no) "no"
+ match-type (equals|contains|starts-with|ends-with) "contains">
+
+10.6. CARDDAV:limit XML Element
+
+ Name: limit
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies different types of limits that can be applied to
+ the results returned by the server.
+
+
+
+Daboo Standards Track [Page 43]
+
+RFC 6352 CardDAV August 2011
+
+
+ Description: The CARDDAV:limit XML element can be used to specify
+ different types of limits that the client can request the server
+ to apply to the results returned by the server. Currently, only
+ the CARDDAV:nresults limit can be used; other types of limit could
+ be defined in the future.
+
+ Definition:
+
+ <!ELEMENT limit (nresults)>
+
+10.6.1. CARDDAV:nresults XML Element
+
+ Name: nresults
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: Specifies a limit on the number of results returned by the
+ server.
+
+ Description: The CARDDAV:nresults XML element contains a requested
+ maximum number of DAV:response elements to be returned in the
+ response body of a query. The server MAY disregard this limit.
+ The value of this element is an unsigned integer.
+
+ Definition:
+
+ <!ELEMENT nresults (#PCDATA)>
+ <!-- nresults value: unsigned integer, must be digits -->
+
+10.7. CARDDAV:addressbook-multiget XML Element
+
+ Name: addressbook-multiget
+
+ Namespace: urn:ietf:params:xml:ns:carddav
+
+ Purpose: CardDAV report used to retrieve specific address objects
+ via their URIs.
+
+ Description: See Section 8.7.
+
+ Definition:
+
+ <!ELEMENT addressbook-multiget ((DAV:allprop |
+ DAV:propname |
+ DAV:prop)?,
+ DAV:href+)>
+
+
+
+
+
+Daboo Standards Track [Page 44]
+
+RFC 6352 CardDAV August 2011
+
+
+11. Service Discovery via SRV Records
+
+ [RFC2782] defines a DNS-based service discovery protocol that has
+ been widely adopted as a means of locating particular services within
+ a local area network and beyond, using SRV RRs.
+
+ This specification adds two service types for use with SRV records:
+
+ carddav: Identifies a CardDAV server that uses HTTP without TLS
+ [RFC2818].
+
+ carddavs: Identifies a CardDAV server that uses HTTP with TLS
+ [RFC2818].
+
+ Example: non-TLS service record
+
+ _carddav._tcp SRV 0 1 80 addressbook.example.com.
+
+ Example: TLS service
+
+ _carddavs._tcp SRV 0 1 443 addressbook.example.com.
+
+12. Internationalization Considerations
+
+ CardDAV allows internationalized strings to be stored and retrieved
+ for the description of address book collections (see Section 6.2.1).
+
+ The CARDDAV:addressbook-query REPORT (Section 8.6) includes a text
+ searching option controlled by the CARDDAV:text-match element and
+ details of character handling are covered in the description of that
+ element (see Section 10.5.4).
+
+13. Security Considerations
+
+ HTTP protocol transactions are sent in the clear over the network
+ unless protection from snooping is negotiated. This can be
+ accomplished by use of TLS as defined in [RFC2818]. In particular,
+ if HTTP Basic authentication [RFC2617] is available, the server MUST
+ allow TLS to be used at the same time, and it SHOULD prevent use of
+ Basic authentication when TLS is not in use. Clients SHOULD use TLS
+ whenever possible.
+
+ With the ACL extension [RFC3744] present, WebDAV allows control over
+ who can access (read or write) any resource on the WebDAV server. In
+ addition, WebDAV ACL provides for an "inheritance" mechanism, whereby
+ resources may inherit access privileges from other resources. Often,
+ the "other" resource is a parent collection of the resource itself.
+ Servers are able to support address books that are "private"
+
+
+
+Daboo Standards Track [Page 45]
+
+RFC 6352 CardDAV August 2011
+
+
+ (accessible only to the "owner"), "shared" (accessible to the owner
+ and other specified authenticated users), and "public" (accessible to
+ any authenticated or unauthenticated users). When provisioning
+ address books of a particular type, servers MUST ensure that the
+ correct privileges are applied on creation. In particular, private
+ and shared address books MUST NOT be accessible by unauthenticated
+ users (to prevent data from being automatically searched or indexed
+ by web "crawlers").
+
+ Clients SHOULD warn users in an appropriate fashion when they copy or
+ move address data from a private address book to a shared address
+ book or public address book. Clients SHOULD provide a clear
+ indication as to which address books are private, shared, or public.
+ Clients SHOULD provide an appropriate warning when changing access
+ privileges for a private or shared address book with data so as to
+ allow unauthenticated users access.
+
+ This specification currently relies on standard HTTP authentication
+ mechanisms for identifying users. These comprise Basic and Digest
+ authentication [RFC2617] as well as TLS [RFC2818] using client-side
+ certificates.
+
+14. IANA Consideration
+
+ This document uses a URN to describe a new XML namespace conforming
+ to the registry mechanism described in [RFC3688].
+
+14.1. Namespace Registration
+
+ Registration request for the carddav namespace:
+
+ URI: urn:ietf:params:xml:ns:carddav
+
+ Registrant Contact: The IESG <iesg@ietf.org>
+
+ XML: None - not applicable for namespace registrations.
+
+15. Acknowledgments
+
+ Thanks go to Lisa Dusseault and Bernard Desruisseaux for their work
+ on CalDAV, on which CardDAV is heavily based. The following
+ individuals contributed their ideas and support for writing this
+ specification: Mike Douglass, Stefan Eissing, Helge Hess, Arnaud
+ Quillaud, Julian Reschke, Elias Sinderson, Greg Stein, Wilfredo
+ Sanchez, and Simon Vaillancourt.
+
+
+
+
+
+
+Daboo Standards Track [Page 46]
+
+RFC 6352 CardDAV August 2011
+
+
+16. References
+
+16.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile",
+ RFC 2426, September 1998.
+
+ [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
+ Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
+ Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+ [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
+ Leach, P., Luotonen, A., and L. Stewart, "HTTP
+ Authentication: Basic and Digest Access Authentication",
+ RFC 2617, June 1999.
+
+ [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
+ specifying the location of services (DNS SRV)", RFC 2782,
+ February 2000.
+
+ [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
+
+ [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
+ Whitehead, "Versioning Extensions to WebDAV
+ (Web Distributed Authoring and Versioning)", RFC 3253,
+ March 2002.
+
+ [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
+ January 2004.
+
+ [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
+ Distributed Authoring and Versioning (WebDAV)
+ Access Control Protocol", RFC 3744, May 2004.
+
+ [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
+ Application Protocol Collation Registry", RFC 4790,
+ March 2007.
+
+ [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
+
+ [RFC5051] Crispin, M., "i;unicode-casemap - Simple Unicode Collation
+ Algorithm", RFC 5051, October 2007.
+
+
+
+
+
+Daboo Standards Track [Page 47]
+
+RFC 6352 CardDAV August 2011
+
+
+ [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+ (TLS) Protocol Version 1.2", RFC 5246, August 2008.
+
+ [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
+ Housley, R., and W. Polk, "Internet X.509 Public Key
+ Infrastructure Certificate and Certificate Revocation List
+ (CRL) Profile", RFC 5280, May 2008.
+
+ [RFC5397] Sanchez, W. and C. Daboo, "WebDAV Current Principal
+ Extension", RFC 5397, December 2008.
+
+ [RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring
+ and Versioning (WebDAV)", RFC 5689, September 2009.
+
+ [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
+ August 2011.
+
+ [W3C.REC-xml-20081126]
+ Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and
+ F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
+ Edition)", World Wide Web Consortium Recommendation REC-
+ xml-20081126, November 2008,
+ <http://www.w3.org/TR/2008/REC-xml-20081126>.
+
+16.2. Informative References
+
+ [IMSP] Myers, J., "IMSP - Internet Message Support Protocol",
+ Work in Progress, June 1995.
+
+ [RFC2244] Newman, C. and J. Myers, "ACAP -- Application
+ Configuration Access Protocol", RFC 2244, November 1997.
+
+ [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol
+ (LDAP): Technical Specification Road Map", RFC 4510,
+ June 2006.
+
+Author's Address
+
+ Cyrus Daboo
+ Apple, Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ EMail: cyrus@daboo.name
+ URI: http://www.apple.com/
+
+
+
+
+
+Daboo Standards Track [Page 48]
+
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-23 15:30:21 +0000