Re: Feedback on Contacts API based on test suite development/prototype

Dominique Hazael-Massieux wrote:
> Hi,
>
> As alluded earlier [1], I encountered some bugs while developing the
> first set of test cases for the Contacts API, which I'm reporting below.
>
> == Lacuna values ==
> null values are required for fields that don't appear in the fields
> parameter of the find() method; but what should be returned when a field
> is requested, but doesn't have a defined value in the underlying address
> book entry: null, undefined or "" (empty string)?
>
> for instance, say the developer asks for
>     navigator.contacts.find(["displayName"], success);
> the user selects a contact doesn't have a displayName, what should the
> resulting contact object look like:
> =>  {displayName: ""}, {displayName: null} or {displayName: undefined}

The spec says: "If a supported attribute has not been assigned a value 
by the user or the implementation, then this attribute must still be 
present in the resulting Contact object and must have a value of null".

Therefore, the object will be {displayName: null}.

>
> How does that apply for composed field?
>      navigator.contacts.find(["name.givenName"], success);
> =>    {name:{givenName:""}}, {name:{givenName:null}},
> {name:{givenName:undefined}}
> or
> =>   {name:null} (resp. undefined, "")

It will be {name: null}. Any additional prose to make that clearer is 
welcome.

>
> What about arrays of composed fields?
>       navigator.contacts.find(["emails.value"], success);
> =>  {emails:[]},
> or
> =>   {emails: null} (resp undefined, "")
> or
> =>  {emails: [{value:null}]  (resp undefined, "")

It will be {emails: null}. Again, if that needs clarifying then please 
consider proposing some normative text to be included.

>
> == displayName vs name.formatted ==
> It's not entirely clear what's the relationship (if any) between
> displayName and name.formatted; is it that name.formatted is required to
> have include all the defined name.* fields?

Perhaps we should merge displayName and name.formatted in to displayName?

>
> == type in ContactField, ContactField.value as URLs ==
> The "type" property in ContactField should be more prescribing in terms
> of possible values: PoCo defines canonical values that apply to almost
> all fields, and defines specific types for some.
>
> This also strongly relate to the comment I sent as part of another
> thread:
> http://lists.w3.org/Archives/Public/public-device-apis/2011May/0026.html
>
> I think all value fields in ContactField properties can be URLs
> (mailto:, tel:, gtalk:, data:, etc), and so we should enforce this in
> the spec. This will make it much easier to re-use the underlying data on
> the Web.

I'm unsure how we would enforce this amongst developers. A DOMString 
parameter is a free-form attribute that takes any String based value 
whether that is a URI or some other non-URI based syntax.

>
> == Multiple characteristic for ContactField ==
> vCard allows to make a given phone number as being an office number
> ("work"), and a voice line ("voice") [in opposition e.g. to a fax]. I
> don't think we can represent this.

On the other hand, Portable Contacts defines a DOMString for the 'type' 
attribute as we have in our spec.

> This raises two questions:
> * is it an acceptable loss of expressiveness for this version of the
> API?

According to Portable Contacts, yes.

> * if it is, should we enforce a specific conversion from vcard for the
> impacted fields?

We could follow Portable Contacts example and define canonical values. 
Portable Contacts doesn't define conversion from vcard fields and even 
if we did, they should probably also apply to Portable Contacts and 
therefore be included in that spec initially.

>
> == Characterizing addresses ==
> Both PoCo and vCard allow to mark an address as being "work" vs "home".
> Our data model doesn't allow to reflect that.

Added to the spec (see diff log: 
http://dev.w3.org/cvsweb/2009/dap/contacts/Overview.html.diff?r1=1.127;r2=1.128;f=h).
>
> == Mismatch with Geolocation v2 Address interface ==
> Our address interface doesn't match the one proposed in Geo v2:
> http://dev.w3.org/geo/api/spec-source-v2.html#address_interface
>
> While I understand our need to align with the schemas defined in vCard
> or PoCo in terms of granularity of fields, I think we should at least
> align on the names of common fields (e.g. "locality" vs "city").

I've also been asked about this privately. I'm not really sure how the 
Geolocation WG are justifying their choice of the Address interface 
parameters provided although they do not provide any mapping to Portable 
Contacts address parameters AFAICS.

>
> == updatedSince option ==
> The updatedSince property of ContactFindOptions seems at odds with the
> way the rest of the options are used.
>
> My understanding is that the parameters in ContactFindOptions are meant
> to guide the user selection ("multiple" allows to select more than one
> contact, "filter" allows to pre-filter the list of contacts shown to the
> user). Would "updatedSince" only show contacts that have been updated
> since a certain date? Would the user be able to select other contacts?
> Why do we single out specifically the update time as a way to filter
> contacts lists in a more advanced fashion?

updatedSince is a Date object and is not intended to match the revision 
Data attribute in a Contact object but only match any revision 
attributes that are 'later than or equal to' the provided updatedSince 
data. As such it's a special filter option for a special filter type ('>=').

>
> I'm not quite sure what's the use case behind "updatedSince" is, but I
> think we should drop it in v1 unless these use cases are compelling.

I can agree with dropping this. We can always add such things back to 
the API at a later date if required.

>
> == Permissions language ==
> Both the "security and privacy" section (as noted earlier [2]), and the
> defined error codes suggest a permission mechanism; given how we
> envision the interaction for Contacts, I don't think there is a notion
> of revokable permissions, and so the relevant language and error code
> should be removed.

I'm not sure I follow. To what language and error codes are you 
referring here?

>
> == INVALID_ARGUMENT_ERROR ==
> When would INVALID_ARGUMENT_ERROR be raised? Note that Web IDL already
> triggers exceptions when a function is invoked with the wrong number of
> parameters, or with null parameters on non-nullable ones.

INVALID_ARGUMENT_ERROR is raised when the fields parameter of a find() 
operation is an empty string.

>
> == Definition of composed attributes ==
> The definition of composed attributes refer to "array, sequences,
> object, any"; but in fact, the API only uses array and object, so I
> suggest dropping the references to others.

Removed 'sequence' and 'any' from the latest draft.

>
> The following sentence says "contain information only available only
> through child attributes of that object", but array don't have "child
> attributes", so this should be reworded to work for both objects and
> arrays.

Reworded this sentence in the latest draft.

>
> == Requirements on Contact instances ==
> The API says:
> "Each Contact instance must include a non-empty id value."
> "Each Contact must include either a displayName or the name attribute."
>
> I don't think either makes sense, and they run counter to data
> minimization. I think the goal is for compatibility with PoCo, but I
> think this is the wrong level to address it. It would be up to
> developers to requests id, displayName (or name) if they want to have
> enough data to interact with PoCo objects.

Above I mentioned that we may be able to combine displayName and name 
attributes. Let's work on this in the coming days to find a solution.

Thanks for the feedback.

- Rich
>
> Dom
>
> 1.
> http://lists.w3.org/Archives/Public/public-device-apis/2011May/0028.html
> 2.
> http://lists.w3.org/Archives/Public/public-device-apis/2011May/0009.html
>
>

Received on Wednesday, 25 May 2011 12:44:52 UTC