Feedback on Contacts API based on test suite development/prototype

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} 

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, "")

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

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

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

== 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. This raises two questions:
* is it an acceptable loss of expressiveness for this version of the
API?
* if it is, should we enforce a specific conversion from vcard for the
impacted fields?

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

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

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

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.

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

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

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

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.

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

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 07:59:13 UTC