- From: Dominique Hazael-Massieux <dom@w3.org>
- Date: Wed, 25 May 2011 09:58:55 +0200
- To: Rich Tibbett <richt@opera.com>
- Cc: public-device-apis@w3.org
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