Re: [contacts] Updated draft available

On Wed, Sep 15, 2010 at 11:47 AM, Rich Tibbett <rich.tibbett@gmail.com>wrote:

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


Hi Dom,

I've updated the Contacts spec inline with this feedback. The relevant CVS
diff is here:
http://dev.w3.org/cvsweb/2009/dap/contacts/Overview.html.diff?r1=1.86&r2=1.87&f=h

Please take a look and let me know if there are still any items that you
would like me to address further.

Thanks,

Rich