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

[Julian Reschke <[e-mail]>]

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? 



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.


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].


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.


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?

    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.

    o  MUST support WebDAV ACL [RFC3744];

    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.

    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>.

    o  MUST support all address book REPORTs defined in ,xref
       target="reports"/> of this document; and

(XML in draft source broken)


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)?

    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?


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.


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


in "6.2.  Address Book Properties"

Make statement about behaviour with DAV:allprop exactly once here, and 
remove it from all subsequent subsections.


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.


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)?


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.

    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)

    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.

       (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

       (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.


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.

       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.

       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.


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.

       (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?"


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?

    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.


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.


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?


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.

    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.

    Clients MUST only use collations from the list advertised by the
    server.

That requirement is useless.


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.


in "8.7.  CARDDAV:addressbook-multiget Report"

    Support for the addressbook-multiget REPORT is REQUIRED.

Why?

-------------

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.


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 -->


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.

in "1.1.  IMSP"

In the list (and subsequent list), please consistently end sentences 
with a dot.


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.


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?


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).


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.


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).


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"


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.




Best regards, Julian