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

Hi,

Thanks for the changes you've already made; further feedback embedded
below.

Le mercredi 25 mai 2011 à 14:44 +0200, Rich Tibbett a écrit :
> 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".

Right, I guess I had missed this!

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

I think the sentence you copied probably covers it.


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

I don't think you replied to that one.

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

Hmm... We don't have to enforce this for developers, since so far
Contact objects would be created by the browser, not developers.

That said, we could/should enforce this by using URL objects rather than
DOMString, based on the "proposed" URL API
https://docs.google.com/document/edit?id=1r_VTFKApVOaNIkocrg0z-t7lZgzisTuGTXkdzAk4gLU&hl=en&pli=1#

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

As I noted above, I think we should import the canonical values from
Portable Contacts.

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

OK; I guess this means PoCo is our main point of reference. I still
think an appendix about mapping from vCard would be a useful addition,
but I don't think it's critical to move to Last Call.

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

Maybe we should suggest to the Geolocation group to update their
interface then?

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

I'm not sure I understand this.

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

Good.

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

        "Those permissions that are acquired through the user interface
        and that are preserved beyond the current browsing session (i.e.
        beyond the time when the browsing context is navigated to
        another URL) must be revocable and a user agent must respect
        revoked permissions."
I don't think persistent permissions make sense for the API.

        "const unsigned short PERMISSION_DENIED_ERROR = 20;"
I don't know when that error code would be triggered.


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

Right, but that wasn't the case when I sent this :)

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

Note that my point wasn't at all about the duplication of
name/displayName. My point is that requiring any of these attributes to
be always filled doesn't make sense.

Taking a concrete example: let's say I have this application that colors
countries in a world map when I have someone in my addressbook that
lives in that country.

To get that data, I would use
 navigator.contacts.find([addresses.country], success, null,
{multiple:true};

The current spec requires the user agent to always send the contact id,
name and display name in addition to the address, even if I as a
developer didn't ask for them (and have no use of them).

I don't see why we require to always set these fields, and as I
mentioned, this goes contrary to data minimization. So I suggest
removing that requirement.

(it probably made some sense when the interface was also used to create
new contacts, but in a read-only context, this doesn't make sense, to me
at least)

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 13:22:23 UTC