Re: [contacts] Updated draft available

On Wed, Sep 15, 2010 at 11:04 AM, Dominique Hazael-Massieux <dom@w3.org>wrote:

> Le lundi 13 septembre 2010 à 16:28 +0200, Rich Tibbett a écrit :
> > I've created a new draft of the Contacts API based on feedback
> > received to date: http://dev.w3.org/2009/dap/contacts/ (Ctrl+R to
> > refresh may be required)
> >
> > There will still be a number of items that will require further work
> > in light of the ongoing discussions related to formats. Your feedback
> > on the latest draft would be most appreciated.
>
> I've brought a few editorial changes directly in the document itself,
> mostly to take into the account the fact that the spec is now only about
> find() (and no longer about save() and remove()).
>

Thanks. All the changes are good.


>
> Some comments from a quick new review:
> • why do we have both "limit" and "multiple" in ContactFindOptions?
> wouldn't limit=1 be equivalent to multiple=false?
>

'multiple' is taken from the input file model:
http://dev.w3.org/html5/markup/input.file.html

I wonder whether we could remove 'limit' as it doesn't render in the
resulting contacts picker and could be confusing if the contacts picker
suddenly stops you from selecting more than X contacts to share. Also, we
probably don't need an upper limit on reflection.

>
> • you imported startDate/endDate for the organization data; while I can
> see it being useful in a social network, that seems somewhat of an
> overkill for an addressbook; that said, it probably doesn't hurt to have
> it included if that facilitates interoperability
>

It actually doesn't facilitate interoperability.

The Portable Contacts draft re-invents the organisations element from the
corresponding vCard organization component. I'd suggest we go with the vCard
format for organization and let any portable contacts specific fields be
defined as extensions to the spec (and let them live and die based on
implementation design choices).


>
> • I wonder if xs:dateTime is the best format for the updatedSince option
> in ContactFindOptions; shouldn't we using the EcmaScript Date interface
> instead?
>

We should use the Date interface here. I will change this.


>
> • rather than “complex”, I would use the word “composed” to qualify
> attributes that are not directly accessible
>

It makes more sense and I will define the meaning of composed to be 'an
object or array' rather than a simple DOMString-like attribute.


>
> • I don't recall any discussion on the search sorting algorithm; was
> this inspired from a similar algorithm somewhere else? I'm not sure the
> API should impose anything on sorting, I would prefer leaving this to
> external libraries
>

Search sorting is increasingly becoming unwieldy and a pain. I'd be in
favour of dropping this proposal. Each contact element has a unique id
element and so the resulting order of search results shouldn't be as
important.

It might be something we want to revisit later on but I'm happy to remove
this.


>
> • requiring (with a MUST) an ill-defined "loose-matching policy" seems a
> bit strong; I would turn that into an implementation advice; the MUST
> can probably still be applied to the fact that implementations need to
> apply the search to all the attributes being retrieved; likewise, I
> would demote the normativeness of the compatibility caseless requirement
> for partial value match
>

I will change this accordingly.


>
> • the search filter algorithm says on successful match that “that
> Contact object must be returned as part of the resulting
> ContactFindSuccessCB” — that’s a bit misleading given that the user may
> or may not choose to include that contact in the data that is provided
> to the application;


This will be tightened up.


> as far as I can tell, the search filter is more a
> hint to allow pre-filtering the list of contacts from which the user
> will select what to send to the app;


That is the intention, yes.


> I think this means also more or
> less dropping (or turning into purely advisory material) the rules for
> processing search filters;
>

When searching across all the different fields it might be useful to know
where matching priorities lie.


>
> • I'm not sure to understand why “The id attribute must always be
> implicitly searchable”; if it really MUST, it should be included in the
> example of fields that needs to be searched just after that sentence
>

In the case that a web app has previously gained access to a user's address
book they may want to target a specific contact object - hence the id
attribute is implicitly searchable. I will clarify this in the spec based on
your suggestion above.


>
> • I think people tend to prefer vendor prefixes to X prefixes for
> extensions, as they avoid conflicting extension names; any reason why
> you chose "X"?
>

I have no preference on this and would like to allow either. "X" prefixed
extensions would be useful for attributes that have been agreed between
implementations or groups but not standardised. Vendor prefixes would be
useful for experimental or implementation specific extensions. Perhaps I
should loosen the wording or include a note about prefixes.


Very helpful feedback Dom. Thanks.

- Rich