Re: [contacts] Contacts API update

Hi Richard,

thanks a lot for this update!

On Dec 11, 2009, at 17:02 , <richard.tibbett@orange-ftgroup.com> <richard.tibbett@orange-ftgroup.com> wrote:
> I look forward to further review and feedback on the mailing list. I
> will aim to remedy any outstanding issues in preparation for a proposed
> FPWD publication in the very near future.

Some notes:

  - in the examples:
        function successContactCallback(updatedContact) {
            // keep myContact updated
            myContact = this.updatedContact;
you want to drop the "this.". The example also gives the impression that the updatedContact is a different object from myContacts (since you have to assign). I would expect them to be the same object (an internal field may have changed, but that's all — the reference is to the same thing). You could probably change the content of that method to just have a comment saying "do some stuff here".

  - It's "consensus" dammit, not "concensus" ;-)

  - 3. In your Note, point 1a seems to be saying that you picked an alignment with Geo because they weren't able to reach consensus on security. That's not very encouraging! Also point 1 isn't very convincing: adopting a security approach because people have had very long discussions about it doesn't fill me with trust. I would only keep 1b and 2, which are much stronger arguments.

  - Note that "user agent" is defined in the conformance section, so that when you make a testable assertion you can use <a>user agent</a> and it'll link to it. It's probably better than "User Agents". I generally try to avoid the plural (A <a>user agent</a>) so that the term is invariant throughout, but that's more of a personal preference.

  - In both 3.1 and 3.2 you are making testable assertions (MUST, etc.) but it's not clear to what extent they can be tested. I think that some of the UA ones are testable (to a point), so we can keep them there, but in 3.2 you have a new conformance product ("Recipients") and it's going to be rather hard to test that (besides probably being outside our charter). For 3.2 I would probably lowercase those musts.

  - 4.1.1 "can be accessed from the DOM" -> "can be accessed". Referring to the DOM for "all objects exposed to scripting by the runtime" is sort of colloquial, and doesn't add much.

  - 4.2 "Multiple address books, taken from different sources, can be represented within this unified address book by specifying a consistent serviceId value as part of individual Contact objects." -> "Multiple address books, taken from different sources, can be represented within this unified address book interface. Contacts from different sources can be distinguished using the serviceId field." Similar thing for "categories". 

  - Silly consistency question: serviceId or serviceID? I guess getElementsById constrains us on that one.

  - It's up to what you prefer but you can add noIDLIn to your configuration to make some of those IDL lines shorter if you want.

  - find(). "When called, it must immediately return" -> "When called, it immediately returns". (Occurs in other places as well).

  - 4.3 "All Contact objects must include ALL attributes" no need to capitalise ALL.

  - On several occasions you discuss NULL values. That's for SQL, in JS it's "null" (look throughout the draft).

  - 4.3.1. I'm not sure that we want to recommend that a UUID URN be used. Saying that it must be globally unique should suffice, and I can see good reasons why someone would want to use something else (e.g. a SHA mailbox as in FOAF).

  - 4.3.2. You should make it clear that it's a deep clone that's desired.

  - "not current exist in Contacts OR the current Contact.id value" No need to scream that OR.

  - "This parameter is OPTIONAL." No need for the 2119 terminology (which would require a conformance product), note that the table and IDL already mark this as optional.

  - 4.4 Is it really necessary to have remove() on a separate interface? It could just be on Contact, and be defined to do nothing if the contact is not in Contacts. It's simpler.

  - 4.5 Given the examples I think that rather than sequence<Foo> you want proper arrays. This would be DOMString[] and ContactNode[] (no need to add the ?, arrays are nullable).

  - serviceId. WHOA! DUDE! WHOA! DANGER RICH ROBINSON! No no no, I don't think that we're going to use ISO9070 FPIs :) Man, I don't want to give ISO 74 Swiss francs to read a document that tells me how to uniquely identify SGML document types. And the registration authority? Apparently they don't have a website, you have to send them paper mail (you remember, the ones that had those little sticky things in the corner?) or call them using a landline. You've been reading vCard/iCal too much ;-) How about this can just be a URI?

  - 4.6. For most of the situations in which this is used, I find this approach nice and simple. But I don't like the way it works for addresses — having them as just text is not only limiting, it is more limiting than what we have in all the inputs save PG (which doesn't have addresses). I think we're better off making this field "any" instead of DOMString, and have ContactAddress defined. The inputs have:

BONDI: country, region, county, city, street, streetNumber, premises, additionalInformation, postalCode
Nokia: street, local, region, code, country

I'd *guess* that we can safely go with: country (two-letter ISO code, preferably), postalCode, region, city, street.

  - 4.7 Do we need grouping? Based on the description, I'm not sure how we determine what the first enumerable ContactProperties attribute is (since it's not ordered). The algorithm doesn't take grouping (or the other options) into account. It looks like you copied the description from sort anyway.

I'm not sure that we want a default limit. It's the kind of number that usually makes no one happy. If people are stupid and run out of memory, they can resort to paging.

For sort, I don't know what the first property is. Would it be better to have sort: ['field1', 'field2'] and descending: true|false where the latter is only meaningful if sort was specified?

  - "6. Contact Search processing rules" Consistent Capitalisation Is Good.

Also these rules are currently underspecified. They don't describe how the options change the returned set. Further I think that we have a choice for array values that is: either they maintain their AND approach and take a value directly (not an array, since we take a single value), or we support the array but if it contains several items those are ORed.

We also need to be a lot clearer about partial matching. It might just be simpler to use pass RegExp objects around. Then again it might not :)


Note that none of the above precludes FPWD (though fixing some of it and flagging some issues for discussion would be nice). I think we should discuss doing so tomorrow.

--
Robin Berjon
  robineko — hired gun, higher standards
  http://robineko.com/

Received on Tuesday, 15 December 2009 12:24:24 UTC