[Ietf-carddav] More comments on draft-daboo-carddav-02
Julian Reschke
julian.reschke at gmx.de
Sun Jul 15 05:22:44 PDT 2007
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:cyrus at daboo.name
NICKNAME:me
NOTE:Example VCard.
ORG:Self Employed
TEL;TYPE=WORK,VOICE:412 605 0499
TEL;TYPE=FAX:412 605 0705
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
More information about the Ietf-carddav
mailing list