WebAPI/ContactsAPI

Contacts API specification

The DAP WG (W3C) has specification sharing this proposal goal [1]. For the moment, the Contacts API proposal might or might not look like the DAP specification.

[1] http://dev.w3.org/2009/dap/contacts/

Goals

Provide DOM API access to the device address book, and the contacts contained therein with a simple minimal API that has a high-degree of interoperability with both device address books and commonly published web contact information (vCard/hCard). - Tantek

Status

See bug 674720.

Proposed API

There is an object in window.navigator named mozContacts with the following interface:

 interface ContactsManager
 {
   attribute Contact[]   contacts;
 };

TO DO: Research/document device-specific address book capabilities and represent using methods on the ContactsManager interface.

The following Contact interface is based vCard4/hCard properties, flattened for the simple/typical case of one address (adr) based on the microformats 2.0 hCard iteration.

 interface Contact {
            attribute DOMString[]            name;
            attribute DOMString[]            honorificPrefix;
            attribute DOMString[]            givenName;
            attribute DOMString[]            additionalName;
            attribute DOMString[]            familyName;
            attribute DOMString[]            honorificSuffix;
            attribute DOMString[]            nickname;
            attribute DOMString[]            email;
            attribute DOMString[]            photo;
            attribute DOMString[]            url;
            attribute DOMString[]            category;
            attribute ContactAddress[]       adr;
            attribute DOMString[]            streetAddress;
            attribute DOMString[]            locality;
            attribute DOMString[]            region;
            attribute DOMString[]            postalCode;
            attribute DOMString[]            countryName;
            attribute DOMString[]            tel;
            attribute DOMString[]            org;
            attribute Date?                  bday;
            attribute DOMString[]            note;
            attribute DOMString[]            impp; /* per RFC 4770, included in vCard4 */
            attribute Date?                  anniversary; /* new in vCard4 */
 };

 interface ContactAddress {
            attribute DOMString[]            streetAddress;
            attribute DOMString[]            locality;
            attribute DOMString[]            region;
            attribute DOMString[]            postalCode;
            attribute DOMString[]            countryName;
 };

Notes of properties left out from vCard4/hCard(2) (subsetting)

• 'logo' left out as 'photo' is used commonly in practice.
• 'post-office-box' and 'extended-address' are left out as in practice such data typically ends up in a long 'street-address' field anyway.
• 'geo', 'latitude', 'longitude' are left out because they are absent from typical device address books (if you've seen a specific device with such fields in the address book, please list it here as a nested list item, preferably with screenshot of the UI).
• 'organization-name' and 'organization-unit' are rarely separately specified, users/publishers preferring to use the simple flat 'org' property instead.

Considered changes

• mozContacts object might move to window.navigator.device;
• more Contact attributes:
  • ringtone (BB, iOS)
  • job-title (BB, iOS)
  • messagetone (BB)
  • phonetic-given-name (iOS)
  • phonetic-family-name (iOS)
  • formal-name (per suggestion from Jonas), like name, but with all "honorable so and so" etc. included as you would formally address or introduce someone. needs examples of publication on the web, and/or device address books that actually include such a field (haven't seen one yet).