Re: Feedback on Contacts API, informed by some Firefox Contacts prototyping

Hi Mike,

Thanks a lot for this feedback!

On Wed, Jun 2, 2010 at 1:34 PM, Robin Berjon <robin@robineko.com> wrote:

>
> On Jun 1, 2010, at 18:49 , Mike Hanson wrote:
> > Nulling of unknown attributes
> >
> > The underlying assumption here is that the schema is fully normative,
> yes?  I'm okay with that in general, though (as I note in the section below)
> I'd really rather start from an existing schema and make assertions about
> which fields are mandatory and which must be removed.
>
> We've been all the way around the block a few times on this one already.
> The great thing with existing schemata is that there are so many to choose
> from. If you have a detailed proposal here, we're more than happy to listen.
>

I *would sincerely like* to start with an existing schema and go from there
- but as Robin says we've been around that block a few times. Perhaps we
could begin to understand the implications of having a full schema included
in the spec...by actually including a full schema in the spec and use that
as a jumping off point. i.e. I'd like to include Portable Contacts in the
spec and let the naysayers work back to an amicable solution from there.

There are then multiple ways in which ALL implementations could manage with
such a full schema - even if the actual SIM, Device, [X-storage] is
incapable of handling such full schema sets on its own. The most promising
solution I've encountered involves an implementation maintaining both the
SIM/Device/[X-storage] -based address book and associating to this a soft
copy address book that supplements such storage points with the necessary
fields for a full Portable Contacts schema. The Android Platform does this
well: all Android Contact Information could be considered a hybrid of
SIM/Device and Networked Contact Information - the storage of individual
properties may be disparate but the net result for user's is a set of
consistent Contact fields.

Equally, the Mozilla Contacts APi also does this well: contact information
can be imported from multiple points (LinkedIn, Yahoo, Gmail, etc) and
aggregated in to a single Contact record based on some matching algorithms.
One of those sources could easily be the SIM or Device, which for the sake
of argument, do not support a PoCo schema, supplemented with data from other
sources. The links to those original attribute sources can be maintained
internally by the implementation within such a soft copy address book that
is used by the Contacts API.

Hopefully that made some sense and I'd be interested in exploring that
approach further..or explaining it further if it doesn't make immediate
sense!

>
> > multiple option
> >
> > The presence of "multiple" in the options suggests that a behavior should
> be defined in (7) to indicate which match wins in the non-multiple case.
>  First one wins?
>
> Good catch. I'm guess that if there's a sort, it's the first, otherwise
> it's whatever the implementation wants.
>
>
I'd like to suggest that: if the 'multiple' field is false, the Contacts
Picker itself will not allow more than one record to be selected and if the
'multiple' field is set to true then allow the user to select one or more
records in the Contacts Picker. So the selection by the user of one or more
fields is directly enforced by the Contacts Picker rather than having to
have anything more complex included in the spec.


> > Caller provides list of fields
> >
> > I am partial to an option that allows the web content to indicate which
> fields of the person record they want (which allows us to construct a UI
> where the user grants, or denies, access to individual fields).  The
> presumption is that web content would never receive more data than they
> asked for, and may receive less.  I may be mistaken but I thought this
> feature was in an earlier draft?
>
> It might not be clear enough, but my understanding is that that's still the
> intent. We've talked of improving this by showing the steps in a mock UI. Of
> course, we don't want to constrain the UI, but I agree that that's a
> valuable option.
>

This is still included in the specification. It is the 'fields' parameter of
the find(..) method. The 'filter' attribute of the 'options' parameter is
for providing some pre-text matching to aid the user in selecting the most
appropriate contact (if e.g. the web app knows something about which contact
the user needs to select (such as highlight all users with X phoneNumber in
the Contacts Picker UI to guide the user's record selection).

If it's only the UI that is causing concern I can add checkboxes next to
'Requested Info' attributes in the demo UI (see screenshots in [1] for
current Contacts Picker demo UI)?


>
> > RFC2119 and Section 4.2:
> >
> > The use of MUST language to restrict the behavior of a website that acts
> as a client to Contacts is a nice thought but feels totally unenforceable.
>  RFC2119 is intended to protect protocol interoperability, not to make moral
> claims about the use of an API, and using it in this way muddies the water a
> bit.  The fact is, bad actors will attempt to abuse this API, and in some
> cases they will succeed; we should put our effort into countermeasures.
>
> Yeah, we know. There's already an action to change that section to match
> text that we have, it just hasn't been done.
>

I'll get on it and we'll see the lie of the land next week.

>
> > I note that the schema presented in the draft does not include birthday,
> which was demanded by one of the use cases in a prior draft.  A standardized
> schema that has already been through community review would help avoid
> omissions like that.
>
> Yup.
>

It turned out that the 'birthday' attribute was not quite as widely
supported as we'd hoped and when choosing the essential, minimalist and
interoperable set Contact Schema to use in the first instance of the spec,
'birthday' simply didn't make the cut (like lots of other vCard attributes
perhaps not supported in e.g. the lamest of SIMs). This doesn't excuse the
fact that it was/is a requirement and is a nod to the larger issue of
including an existing, complete and full Contacts schema in the
ContactProperties interface in to the spec.


>
> > My preference would be for Portable Contacts, which is imperfect but has
> some momentum at this point.
>
>
+1. Not because it's perfect but because one of its stated objectives is to
encompass vCard attributes so vCard compatibility is implied, killing two
rather nasty birds with a single stone (if a soft copy address book approach
as discussed above can be mandated for implementation).


> Portable Contacts is a workable option, one thing that I'm unsure of is
> whether we can do without the fields grandfathered from OpenSocial (drinker,
> scaredOf, lookingFor, favouriteTwilightCharacter, etc.). There are also a
> few things I don't like much, e.g. that it's unclear whether country is
> "France" (useless) or "fr".
>
> More importantly, the breadth of PC means that we need to decide what to do
> when the underlying store can't handle a field that the developer is trying
> to add (e.g. you're exposing the rather daft iPhone address book). It's nice
> to have a schema that people use, but if half the time when you code against
> it half your fields just get lost, you don't have much of a useful spec
> (hence the current minimalistic approach).
>
> > * The draft defines "name" as a singular field, which is insufficient for
> most applications and is particularly difficult for some localizations.  A
> givenName and familyName is important, and cultural norms differ about to
> handle these two fields.  Many mobile applications also demand a phonetic
> name field to enable voice recognition hints.  A structured "name" field
> leads to the desire for a "displayName", which would be identical to the
> "name" currently present in the draft.  Parsing human names is a really
> painful problem and if we have structured data I'd really prefer to maintain
> it.
>
> We had that in one of the initial drafts, I'm unsure as to where it went.
>

Yep, this one in one of the initial drafts but was removed:

As you say, parsing structured names is a really painful problem. If we just
want to go with structured data for individual firstName, lastName, prefix,
suffix, etc attributes then this can easily be remedied by removing the
current name attribute and replacing with a complex name object with
individual name part attributes.

If we want to have both a displayName and individual firstName, lastName,
prefix, suffix,... attributes we need need to document an "implied 'n'
optimization" such as the one include in the hCard specification [2]. A
non-null displayName should implicitly produce individual name fields and
conversely individual name fields should implicitly produce a displayName.
The same thing applies to displayAddress vs. individual street, city,
zipCode,... attributes > "implied 'addr' optimizations"?


>
> > * Is an extension mechanism formally off the table?
>
> We've mostly talked about vendor prefixes. Do you have a specific proposal?
>
>
Any proposals welcome but yes we've spoken about vendor prefixes (such as
'xFooName').


>
> [0] http://dev.w3.org/2006/webapi/IndexedDB/
>
>
Thanks,

Richard


[1] http://lists.w3.org/Archives/Public/public-device-apis/2010Jun/0007.html

[2] http://microformats.org/wiki/hcard#Implied_.22n.22_Optimization