Re: [Ietf-carddav] More comments on draft-daboo-carddav-02

[Cyrus Daboo <[e-mail]>]

Hi Julian,
Thanks for your detailed comments. Sorry it took a while to respond.

--On July 15, 2007 2:22:44 PM +0200 Julian Reschke <[e-mail]> 
wrote:

> More detailed comments on draft-daboo-carddav-02...:
>
> In general, please replace all references to RFC2518 with RFC4918.
>
> In "1.5.  WebDAV for Address Books"
>
>     2.  Stateless nature of protocol can result in more data being sent
>         with each transaction to maintain per-user session across
>         requests.
>
> I guess that should either go, or be expanded a bit; the way it's worded
> right now I don't understand it. Is this about sending state in cookies?

I guess I am trying to make a comparison here with IMAP where server state 
is communicated to the client during the course of a session via 
unsolicited responses or via the IDLE mechanism. As a result clients have 
to poll to get state changes, and right now they have to poll an entire 
collection to find what has changed, been added or deleted (though I hope 
the proposed collection synchronization extension will help address that).

I can certainly expand the text to describe this more in terms of having to 
do a full re-synchronization to get state.

> In "2.1.  Notational Conventions"
>
>     The term "protected" is used in the Conformance field of property
>     definitions as defined in Section 1.4.2 of [RFC3253].
>
> Section 15 of RFC4918.

Fixed.

> In "2.2.  XML Namespaces and Processing"
>
>     Processing of XML by CardDAV clients and servers MUST follow the
>     rules described in [RFC2518], in particular Section 14, and Appendix
>     3 of that specification.
>
> Appendix A of [RFC4918].

Fixed.

> In "2.3.  Method Preconditions and Postconditions"
>
> Just cite RFC4918, Section 16. Note the current text is incompatible with
> RFC4918 with respect to DAV:error in DA:multistatus.

I will remove that section in its entirety as the spec will now cite 4918 
instead of 2518.

> In "3.  Requirements Overview"
>
>     o  MUST support vCard [RFC2426] as a media type for the address
>        object resource format;
>
> Is it clear what this requirement means?

That should be explained in a little more detail by noting that (as with 
CalDAV) we are not restricting ourselves to a single syntax for 
"vCard-like" data. i.e. the spec has been designed to allow other variants 
of vCard syntax to be used (e.g. the Jabber foundation's xcard or perhaps 
hcard). This spec, however, only requires the server to support the 2426 
syntax. This is described in section 5.1. Perhaps I can refer to that from 
this bullet point?

>     o  MUST support WebDAV Class 1 [RFC2518] (note that
>        [I-D.ietf-webdav-rfc2518bis] describes clarifications to [RFC2518]
>        that aid interoperability);
>
> Should say RFC4918 Class 3.

Fixed.

>     o  MUST support transport over TLS [RFC2246] as defined in [RFC2818]
>        (note that [RFC2246] has been obsoleted by [RFC4346]);
>
> Note: similar text in AtomPub was rejected by IESG. See
> <http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-17.html#
> rfc.section.14> for alternate proposal.

And yet they accepted the same text in CalDAV!

I have now changed this to (which I think follows the ATOMPUB approach you 
linked to):

o MUST support secure transport as defined in [RFC2818] using TLS v1.0 
[RFC2246]
  or a subsequent standards-track version of TLS.

>     o  MUST support ETags [RFC2616] with additional requirements
>        specified in Section 6.3.2.3 of this document;
>
> Nope; see
> <http://lists.w3.org/Archives/Public/w3c-dist-auth/2007JulSep/0006.html>.

More on this below...

>     o  MUST support all address book REPORTs defined in ,xref
>        target="reports"/> of this document; and
>
> (XML in draft source broken)

Fixed.

>
> in "4.1.  Address Book Server"
>
>     A WebDAV repository can advertise itself as a CardDAV server if it
>     supports the functionality defined in this specification at any point
>     within the root of the 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.
>
> Question: when we say "can advertise", would it cause problems when a
> server does NOT advertisue support on anything except address books (and
> descendants)?

Well it has to "advertise" on any resource that includes properties, 
reports etc specific to this spec. So at a minimum that means address book 
collections and principal resources. And no, it should not cause clients a 
problem if it only does that.


>     The CardDAV server or repository is the canonical location for
>     address data and state information.  Clients may submit requests to
>
> Server or repository? Please be consistent. Also, what does it mean
> to be the "canonical location"? Does that rule out a CardDAV server to be
> a proxy to an LDAP server?

OK, I will tidy that up. "Cononical" is really described by the subsequent 
text in that paragraph that discusses how clients should do 
synchronization. That does not rule out a CardDAV server from being a 
"getaway" to another server - it just makes it clear to clients of CardDAV 
how they should treat the server.

>
> in "5.2.  Address Book Collection"
>
>     CardDAV defines the following new resource type for use in WebDAV
>     repositories holding vCard data.
>
> Remove that intro. Section reads completely fine without it.

Done.

>
> in "6.1.1.  Example: Using OPTIONS for the Discovery of Support for
> CardDAV"
>
>     HTTP/1.1 200 OK
>     Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
>     Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT
>     Allow: MKADDRESSBOOK, ACL
>     DAV: 1, 2, access-control, addressbook-access
>     Date: Sat, 11 Nov 2006 09:32:12 GMT
>     Content-Length: 0
>
> DAV: 1, 2, 3, access-control, addressbook-access

Fixed.

> in "6.2.  Address Book Properties"
>
> Make statement about behaviour with DAV:allprop exactly once here, and
> remove it from all subsequent subsections.

4918 has changed the "template" used for property definitions compared to 
2518. I propose to revise what is in CardDAV now along those lines. e.g. 
have "Protected" and "COPY/MOVE" items. In addition have a "DAV:allprop" 
behavior item in the template would be good to. I would prefer having it 
explicitly specified in each property.

> in "6.2.1.  CARDDAV:addressbook-description Property"
>
>     Conformance:  This property MAY be defined on any address book
>        collection.  If defined, it MAY be protected and SHOULD NOT be
>        returned by a PROPFIND DAV:allprop request (as defined in Section
>        12.14.1 of [RFC2518]).  An xml:lang attribute indicating the human
>        language of the description SHOULD be set for this property by
>        clients or through server provisioning.  Servers MUST return any
>        xml:lang attribute if set for the property.
>
> "MAY be defined" is a confusing way to say that it's optional. The
> language about xml:lang is kind of confusing; for instance, I can see
> people understand this that the server should provide the property if the
> client didn't specify it. Bad idea.

>     Description:  If present, the property contains a description of the
>        address book collection that is suitable for presentation to a
>        user.  If not present, the client should assume no description for
>        the address book collection.
>
> Can we just say what it is? If it's not there, it's not there. Please
> don't make things more complicated than they are.

I think the concern here was to make sure server vendors reserved a slot in 
their schema for such a property, for the case where servers had a fixed 
schema and would not allow "arbitrary" properties to be created. Is that a 
real concern or not? If not, then your text is certainly better. If it is a 
concern, then we do need a statement to that effect - but perhaps that can 
be a general statement in the requirements section, and the actual property 
descriptions can follow your simple text.

>
> in "6.2.2.  CARDDAV:supported-address-data Property"
>
>     Purpose:  Specifies what media types are allowed for address object
>        resources in an address book collection.
>
>        ...
>
>     Example:
>
>         <C:supported-address-data
>            xmlns:C="urn:ietf:params:xml:ns:carddav">
>           <C:addressbook-data content-type="text/vcard" version="3.0"/>
>         </C:supported-address-data>
>
> Why is this needed? How are media types with different parameters
> treated (such as text/directory;profile=vcard)?

As discussed earlier, other syntaxes for vCard-like data may be offered by 
servers in the future, so this property identifies what a server supports.

Note that text/vcard does not actually exist as a MIME type right now. I am 
hoping that the vCard revision effort will lead to the introduction of that 
type with the requirement that it be utf-8 text (similar to text/calendar).

>
> in "6.3.1.  MKADDRESSBOOK Method"
>
>     Support for MKADDRESSBOOK 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 MKADDRESSBOOK whenever possible to allow users to create
>     multiple address book collections to help organize their data better.
>
> ...and not required...
>
>     Clients SHOULD use the DAV:displayname property 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 MKADDRESSBOOK
>     request, or alternatively issue a PROPPATCH request to change the
>     DAV:displayname property to the appropriate value immediately after
>     using the MKADDRESSBOOK request.  Clients SHOULD NOT set the DAV:
>     displayname property to be the same as any other address book
>     collection at the same URI "level".  When displaying address book
>
> In WebDAV, there is no requirement that DAV:displayname is unique in a
> collection, and in practice, it may be hard to guarantee. Why is this
> needed? Also, there seems to be an overlap with CARDDAV:description.

That requirement is present to avoid confusing the user with two address 
books that appear to have the same name but are in fact different (e.g. a 
user may think that they have duplicate address books and go and delete one 
on the basis that all its data is in the other).

>     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 empty, the client MAY use
>
> ...property is not set... (this is different from being empty)

Fixed.

>     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.
>
>     If a MKADDRESSBOOK request fails, the server state preceding the
>     request MUST be restored.
>
> Please specify cacheability/safety/idempotence.

OK, I will need to think about that a little bit.

>        (CARDDAV:addressbook-collection-location-bad): The Request-URI
>        MUST identify a location where an address book collection can be
>        created.
>
> CARDDAV:addressbook-collection-location-valid

CARDDAV:addressbook-collection-location-ok matches the one in CalDAV. Fixed.

>        (DAV:needs-privilege): The DAV:bind privilege MUST be granted to
>        the current user.
>
> (1) It's "need-privileges"
> (<http://greenbytes.de/tech/webdav/rfc3744.html#rfc.section.7.1.1>. (2)
> Is it really required to repeat that here? If yes, please include a
> reference to the definition in RFC3744.

Fixed the name. I will leave that in for now, but chances are if we end up 
using an extended MKCOL for this we would "inherit" this pre-condition by 
default.

>
> in "6.3.1.1.  Status Codes"
>
>        201 (Created) - The address book collection resource was created
>        in its entirety.
>
> Please specify what "in its entirety" means or drop it.

Fixed:

201 (Created) - The address book collection resource was created,
and any supplied properties values were set.

>        409 (Conflict) - A collection cannot be made at the Request-URI
>        until one or more intermediate collections have been created.
>
> This is incorrect; it is in conflict with the pre/postcondition
> definitions.

Removed.

>        415 (Unsupported Media Type) - The server does not support the
>        request type of the body.
>
>        507 (Insufficient Storage) - The resource does not have sufficient
>        space to record the state of the resource after the execution of
>        this method.
>
> If the list is not exhaustive anyway, things like 507 or 415 IMHO should
> go. The more you repeat obvious stuff, the harder it is to see what's
> being specified.

Removed.

>
> in "6.3.2.1.  Additional Preconditions for PUT, COPY and MOVE"
>
>     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;
>
> This is already covered by HTTP status 415.

A pre-condition DAV:error can include a more structured response about the 
nature of the error, so when is it appropriate to use that as opposed to a 
status code?

>        (CARDDAV:addressbook-collection-location-ok): In a COPY or MOVE
>        request, when the Request-URI is an address book collection, the
>        Destination-URI MUST identify a location where an address book
>        collection can be created;
>
> "Destination-URI"? Did you mean "The URI specified in the Destination
> header?"

Yes. Fixed.

>
> in  "6.3.2.2.  Non-Standard Properties, and Parameters"
>
> I was momentarily confused because I thought it wasn't about vCard data.
> Maybe include this in the section title?

Fixed.

>     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.  Servers SHOULD ensure that any "private" 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".
>
> Just state the requirement from RFC2426, but don't add an own one.

Actually 2426 does not have a formal requirement for a vendor-id. That is 
something that ought to be fixed in any revision IMHO.

>
> in "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.
>
> Disagree; see above.
>
>     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 and have the DAV:getetag property returned, and 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.
>
> This basically makes it impossible to rewrite content, and still return
> an ETag. I think this is a mistake.

We have obviously been through all this with CalDAV. In the absence of any 
alternative approach, I think we should stick with what CalDAV does in this 
regard. However, a better solution to this is needed and I think its time 
your draft gets more attention so that we can move that or something 
similar forward to address this. I think PATCH is also going to be impacted 
by this too.

>
> 8.  Address Book Reports
>
>     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.
>
> Simplify: (1) this restates what was alredy said. (2) the key here is
> that servers may support the reports elsewhere as well, not that they can
> *advertise* support for them, right?

Not quite: this says that servers must follow the 3253 convention on 
advertising the reports in DAV:supported-report-set, whereas previous 
statements relating to supporting the reports themselves. Since we are 
"inheriting" certain aspects of 3253's report behavior I think it is import 
to be explicit about what is required. Perhaps this is a case where we can 
pull the REPORT method out of 3253 and write it up as a separate extension 
with requirements explicitly stated, then other specs that need to use it 
could reference that.

>
> in "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.
>
> Lots of motivation, not really needed here. Also, I think "default" is
> misleading, as the default for text/* is *not* UTF-8.

As per above I would like to see text/vcard be defined with utf-8 as the 
default.

>     CardDAV servers are REQUIRED to support the "i;ascii-casemap" and
>     "i;octet" collations as described in [RFC4790], and the
>     "i;unicasemap" collation as described in
>     [I-D.crispin-collation-unicasemap], MAY support other collations.
>
> (1) I think for collations that are defined in terms of octet sequences,
> a mapping from vcard needs to be defined (say: UTF-8). (2) Also, I don't
> think this can be guaranteed in practice, for instance when the CardDAV
> server just proxies.

The collations themselves define how mapping or normalization of the input 
data should be done. I don't think we need to state that here.

>     Clients MUST only use collations from the list advertised by the
>     server.
>
> That requirement is useless.

Why? All it says is that clients must attempt to use only those collations 
advertised by the server.

>
> in "8.6.  CARDDAV:addressbook-query Report"
>
> All report definitions must precisely state the semantics of the Depth
> request header.
>
>     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.
>
> Reference definition in RFC3744.

3744 specifically talks about principals which are not relevant here.

>
> in "8.7.  CARDDAV:addressbook-multiget Report"
>
>     Support for the addressbook-multiget REPORT is REQUIRED.
>
> Why?

multiget makes a big difference in performance.

> -------------
>
> Editorial:
>
> in "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.
>     This document defines the "addressbook-access" feature of CardDAV.
>
> I think it would be good to have an editorial note here pointing to the
> vcard mailing list.

Done.

> With respect to DTD fragments:
>
> Please make sure they actually *are* DTD fragment, so for instance replace
>
>         <!ELEMENT addressbook-description (#PCDATA)>
>         PCDATA value: string
>
> by
>
>         <!ELEMENT addressbook-description (#PCDATA)>
>         <!-- PCDATA value: string -->

Fixed.

> in "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 LDAP
>     [RFC2251], IMSP and ACAP [RFC2244], together with SyncML used for
>     synchronization of such data.
>
> Reference for IMSP? Also, expand acronyms on first usage.

Done.

> in "1.1.  IMSP"
>
> In the list (and subsequent list), please consistently end sentences with
> a dot.

Fixed.

> in "4.1.  Address Book Server"
>
>     A WebDAV repository MAY include address data in some parts of its URL
>     namespace, and non-address data in other parts.
>
> I don't think this is any kind of requirement; it just states something
> obvious. Please lowercase the MAY.

Done.

> in "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
>     described below.  The requirements in this section pertain to vCard
>     address data, os formats that follow the semantics of vCard data.
>
> Typo? os->or?

Fixed.

> in "6.2.2.  CARDDAV:supported-address-data Property"
>
>     Conformance:  This property MAY be defined on any address book
>        collection.  If defined, it MUST be protected and SHOULD NOT be
>        returned by a PROPFIND DAV:allprop request (as defined in Section
>        12.14.1 of [RFC2518] ).
>
>     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
>        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.
>
> Please check whitespace around xml2rfc <xref> elements (this repeats
> several times through the draft).

Fixed.

> in "6.3.1.2.  Example - Successful MKADDRESSBOOK request"
>
>     HTTP/1.1 201 Created Date: Fri, 22 Oct 2004 12:17:08 GMT
>     Content-Length: 0
>     Date: Sat, 11 Nov 2006 09:32:12 GMT
>     Cache-Control: no-cache
>
> Two date headers.

Fixed.

> in "6.3.2.  Creating Address Object Resources"
>
>     >> 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:[e-mail]
>     NICKNAME:me
>     NOTE:Example VCard.
>     ORG:Self Employed
>     TEL;TYPE=WORK,VOICE:412 605 0499
>     TEL;TYPE=FAX:[phone]
>     URL:http://www.daboo.name
>     UID:1234-5678-9000-1
>     END:VCARD
>
> Please use example domain names in examples (here: EMAIL and URL).

Fixed.

>
> in "6.3.2.1.  Additional Preconditions for PUT, COPY and MOVE"
>
>     This specification creates additional Preconditions for PUT, COPY and
>     MOVE methods.  These preconditions apply:
>
>        When a PUT operation of an address object resource into an address
>        book collection occurs.
>
>        When a COPY or MOVE operation of an address object resource into
>        an address book collection occurs.
>
> List style: please make it "numbers" or "symbols"

Fixed.

> in "7.1.1.  CARDDAV:addressbook-home-set Property"
>
>      <C:addressbook-home-set xmlns:D="DAV:"
>         xmlns:C="urn:ietf:params:xml:ns:carddav">
>        <D:href>http://addressbook.example.com/bernard/addresses/</D:href>
>      </C:addk-home-set>
>
> Check the end tag.

Fixed.

-- 
Cyrus Daboo