Contacts

Contacts data is kept in db8 database storage as JSON data objects. JSON is a lightweight data-interchange text format based on a subset of the JavaScript programming language that is easy for humans to read and write and for machines to parse and generate. Like XML, JSON contains name/value pair collections and ordered lists of values (i.e., arrays).

Using the db8 JavaScript wrapper API calls, you can specify the data object fields you want to retrieve using SQL-like queries and then reference them using standard JavaScript notation, i.e., object.field.

Contacts Data Object Schemas and Kinds

The schemas below detail the layout of Contacts JSON data objects; 3rd party applications can access this data using the db8 JavaScript wrapper provided with Palm's JavaScript Foundation libraries. See the db8 documentation for detailed information on including and using these calls in your JavaScript code. Examples of db8 JavaScript calls are provided with each of the data type schemas detailed below.

For each readable data object, you need to know the name of its kind. Kind objects in db8 define the indexes and access control for stored JSON data objects. You must specify the kind when accessing data objects of that kind.

NOTES

The schemas below do not include the "_id", "_rev" and "_kind" fields that are automatically assigned to each data object once it is stored. If you retrieve data objects in their entirety, you will see these fields. See the db8 documentation for information about these special fields and how they are used.
The example db8 JavaScript calls shown in the documentation below use a Foundation Library construct known as a "future", which is a kind of asynchronous callback.
Each kind name is appended with a ":#" string indicating its version.

Schema	Ref'd by	Kind
Contact		com.palm.contact:1
ContactAccount	Contact
ContactAddress	ContactOrganization ContactPluralAddress (extends)
ContactCustomField	Contact
ContactName	Contact Person
ContactOrganization	Contact Person
ContactPhotoField	Contact
ContactPluralAddress	Contact
ContactPluralField	Contact ContactPluralAddress (extends) ContactPhotoField (extends) Person
ContactPluralIMAddress	Contact
DefaultPropertyHash	Favorite
FavoritablePersonPluralField	Person
Favorite
Person		com.palm.person:1
PersonName	Person
PersonPluralAddress	Person
PersonPluralField	FavoritablePersonPluralField (extends)
PersonPluralIMAddress	Person
PersonPluralPhoneNumber	Person
PersonRingtone	Person

Contact

Schema

{
   remoteId     : string,
   accountId    : string,
   name         : ContactName,
   nickname     : string,
   birthday     : string,
   anniversary  : string,
   gender       : string,
   note         : string,
   emails       : ContactPluralField array,
   urls         : ContactPluralField array,
   phoneNumbers : ContactPluralField array,
   ims          : ContactPluralIMAddress array,
   photos       : ContactPhotoField array,
   addresses    : ContactPluralAddress array, 
   organizations: ContactOrganization array,
   accounts     : ContactAccount array,  
   tags         : string array,  
   customFields : ContactCustomField array,    
   relations    : ContactPluralField array           
}

Elements

Element	Required	Type	Description
remoteId	No	string	Contact's remote ID. Must remain the same for this contact across multiple syncs, restores, and devices.
accountId	Yes	string	Contact's db8 account object ID.
name	Yes	ContactName	The broken-out components and fully formatted version of the contact's real name.
nickname	No	string	Contact's casual name in real life.
birthday	Yes	string	Contact's birthday in the format yyyy-mm-dd (using 0000 when the year is unknown).
anniversary	Yes	string	Contact's wedding anniversary in the format yyyy-mm-dd (using 0000 when the year is unknown).
gender	Yes	string	Contact's gender: "male" \| "female" \| "undisclosed".
note	No	string	Note about this contact.
emails	No	ContactPluralField array	Contact's e-mail addresses.
urls	No	ContactPluralField array	Contact's Web page URLs.
phoneNumbers	No	ContactPluralField array	Contact's phone numbers including home, mobile, personal fax, work fax, personal, sim, main, and pager.
ims	No	ContactPluralIMAddress array	Contact's instant messaging addresses.
photos	No	ContactPhotoField array	Contact's photos. Whenever possible, the value field should be the remote URL of the photo. Instead of the canonical values for type, this field defines: type_big and type_square.
addresses	No	ContactPluralAddress array	Physical mailing addresses for this Contact.
organizations	No	ContactOrganization array	Contact's current or past affiliated organizations.
accounts	No	ContactAccount array	Contact's online accounts.
tags	No	string array	Contact's user-defined categories or labels.
customFields	No	ContactCustomField array	Contact's custom key-value data pairs.
relations	No	ContactPluralField array	Contact's relatives. Instead of the standard types, this field defines: Assistant, Brother, Child, Domestic Partner, Father, Friend, Manager, Mother, Parent, Partner, Referred By, Relative, Sister, Spouse, Other.

Example

      {
         "_id":"++HCZe+Cyrh4hRh1",
         "_kind":"com.palm.contact.facebook:1",
         "_rev":3227,
         "__partial":true,
         "accountId":"++HCZdsbJw7iuN8s",
         "birthday":"1980-08-01",
         "emails":[
            {
               "_id":"c9c",
               "type":"type_home",
               "value":"adamsjl@email.unc.edu"
            }
         ],
         "name":{
            "familyName":"Adams",
            "givenName":"Jacob"
         },
         "photos":[
            {
               "_id":"c9d",
               "localPath":"/var/file-cache/contactphoto/JIW/DBgAH1.jpg",
               "type":"type_big",
               "value":"http://profile.ak.fbcdn.net/profile-ak-snc1/v229/755/112/n2728710_5129.jpg"
            },
            {
               "_id":"c9e",
               "localPath":"/var/file-cache/contactphoto/W1Y/KrwAH2.jpg",
               "type":"type_square",
               "value":"http://profile.ak.fbcdn.net/hprofile-ak-snc4/hs624.ash1/27407_2728710_8698_q.jpg"
            }
         ]
      }

Contact Account

Schema

{
   "domain"   : string,
   "userName" : string, 
   "userid"   : string   
}

Elements

Element	Required	Type	Description
domain	Yes	string	The top-most authoritative domain for this account.
userName	Yes	string	An alphanumeric user name, usually chosen by the user
userid	No	string	A user ID number, usually chosen automatically, and usually numeric but sometimes alphanumeric.

ContactAddress

Schema

{
   "streetAddress" : string,
   "locality"      : string,
   "region"        : string,
   "postalCode"    : string,
   "country"       : string
}

Elements

Element	Required	Type	Description
streetAddress	No	boolean	The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information.
locality	No	string	The city or locality component.
region	No	string	The state or region component.
postalCode	No	string	The zipcode or postal code component.
country	No	string	The country name component.

ContactCustomField

Schema

{
   "name"  : string,
   "value" : string                 
}

Elements

Element	Required	Type	Description
name	Yes	string	Custom field name.
value	Yes	string	Custom field value.

ContactName

Schema

{
   "familyName"      : string,
   "givenName"       : string,
   "middleName"      : string,
   "honorificPrefix" : string,
   "honorificSuffix" : string                        
}

Elements

Element	Required	Type	Description
familyName	No	string	The family name of this Contact, or 'Last Name' in most Western languages.
givenName	No	string	The given name of this Contact, or 'First Name' in most Western languages.
middleName	No	string	The middle name(s) of this Contact.
honorificPrefix	No	string	The honorific prefix(es) of this Contact, or 'Title' in most Western languages.
honorificSuffix	No	string	The honorifix suffix(es) of this Contact, or 'Suffix' in most Western languages.

ContactOrganization

Schema

{
   "name"        : string,
   "department"  : string,
   "title"       : string,
   "type"        : string,
   "startDate"   : string,
   "endDate"     : string, 
   "location"    : ContactAddress object,
   "description" : string,
   "primary"     : boolean               
}

Elements

Element	Required	Type	Description
name	Yes	string	Organization name.
department	No	string	Department in organization.
title	No	string	Job title or role in organization.
type	No	string	Organization type, i.e., "school", "job".
startDate	No	string	Date contact joined organization.
endDate	No	string	Date contact left organization.
location	No	ContactAddress	Organization's physical location.
description	No	string	Description of contact's role in organization.
primary	No	boolean	Is this instance of the Plural field the primary or preferred value for this field.

ContactPhotoField

Schema

{
    extends    : ContactPluralField
   "localPath" : string                       
}

Elements

Element	Required	Type	Description
localPath	Yes	string	Photo's local file path, i.e., "/some/path/to/photo.png". Typically this is a filecache path.

ContactPluralAddress

Schema

extends ContactAddress and ContactPluralField
{                      
}

ContactPluralField

Schema

{
   "value"     : string,
   "type"      : string,
   "primary"   : boolean                       
}

Elements

Element	Required	Type	Description
value	Yes	string	Plural field value.
type	No	string	Plural field type. Must be "work", "home", "other", or others as described in the Contact schema.
primary	No	boolean	Indicates if this Plural Field instance is the primary or preferred value.

ContactPluralIMAddress

Schema

{
    extends : ContactPluralField
   "type"   : string,
   "label"  : string                      
}

Elements

Element	Required	Type	Description
type	Yes	string	A string representing the service this IM Address is valid on. Current values are: service_aim, service_google, service_irc, service_yjp, service_lcs, service_dotmac, service_icq, service_xmpp, service_msn, service_skype, service_qq, service_jabber, service_yahoo, and service_default.
label	No	string	The label of field for this instance, usually used to label the preferred function of the given contact information. Must be "label_work", "label_home", "label_other", (others as described above in the Contact schema).

DefaultPropertyHash

Schema

{
   "value"        : string,
   "type"         : string,
   "favoriteData" : any                      
}

Elements

Element	Required	Type	Description
value	Yes	string	Hash of the property's value.
type	Yes	string	Property type: PhoneNumber, Email, IMAddress, ...
favoriteData	Yes	any	Holds all the app specific data for the default favorite contact point.

FavoritablePersonPluralField

Schema

{   
   extends        : PersonPluralField,
   "favoriteData" : any       
}

Elements

Element	Required	Type	Description
favoriteData	No	any	Keys are the appIds and the values are objects holding listIndex, auxData.

DefaultPropertyHash

Schema

{
   "value"        : string,
   "type"         : string,
   "favoriteData" : any                      
}

Elements

Element	Required	Type	Description
value	Yes	string	Hash of the property's value.
type	Yes	string	Property type: PhoneNumber, Email, IMAddress, ...
favoriteData	Yes	any	Holds all the app specific data for the default favorite contact point.

Favorite

Schema

{   
   "contactBackupHash"     : string,
   "defaultPropertyHashes" : DefaultPropertyHash array       
}

Elements

Element	Required	Type	Description
contactBackupHash	Yes	string	Contact backup hash for the contact linked to a favorite person.
defaultPropertyHashes	Yes	DefaultPropertyHash array	Array that holds a hashed version of the default value for each property that can be defaulted on a favorite.

Person

Schema

{
   "launcherId"   : string,
   "favorite"     : boolean,
   "contactIds"   : string array,
   "sortKey"      : string,
   "name"         : ContactName,
   "names"        : PersonName array,
   "nickname"     : string,
   "organization" : ContactOrganization,
   "searchTerms"  : string array,
   "emails"       : FavoritablePersonPluralField array,
   "phoneNumbers" : PersonPluralPhoneNumber array,
   "ims"          : PersonPluralIMAddress array,
   "photos"       : {
                       "localPathBig"    : string,
                       "localPathSquare" : string, 
                       "localPathList"   : string,
                       "listPhotoSource" : string,
                       "photoIdBig"      : string,
                       "photoIdSquare"   : string,
                       "contactId"       : string,
                       "accountId"       : string
                    }  
   "addressses"   : PersonPluralAddress array,
   "urls"         : FavoritablePersonPluralField array,
   "notes"        : string array,
   "birthday"     : string,
   "anniversary"  : string,
   "gender"       : string,
   "relations"    : ContactPluralField array,
   "reminder"     : string,
   "ringtone"     : PersonRingtone
}

Elements

Element	Required	Type	Description
launcherId	No	string	The launcherId of this contact. This id is the launchPoint id for this person's launch point on the launcher.
favorite	Yes	boolean	Indicates if this person is a favorite
contactIds	Yes	string array	The db8 IDs of the contacts that make up this person
sortKey	Yes	string	The UI displays records sorted by this field.
name	Yes	ContactName	The broken-out components and fully formatted version of the contact's real name.
names	Yes	PersonName array	The names for all of the contacts linked to this person. Names contain normalized values.
nickname	No	string	The casual way to address this Contact in real life.
organization	No	ContactOrganization	A current organizational affiliation of this Person.
searchTerms	Yes	string array	A few search terms for the Contacts linked to this Person that are not simply items in other properties. Normalized by lowercasing. E.g. for Joe Testerson: ['jtesterson''testersonjoe'])
emails	No	FavoritablePersonPluralField array	De-duped E-mail addresses for all Contacts linked to this Person normalized by lowercasing.
phoneNumbers	No	PersonPluralPhoneNumber array	De-duped Phone numbers for all Contacts linked to this Person normalized by stripping and reversing to allow matching on trailing digits using the prefix operator.
ims	No	PersonPluralIMAddress array	De-duped Instant messaging address for all Contacts linked to this Person normalized by lowercasing.
photos	Yes	inline object	The fields representing the photo for this person.
localPathBig	No	string	The local path of the type_big photo for this person (e.g. /some/path/to/photo.png), if one exists. This is typically in the filecache. At least one of 'localPathBig' and 'localPathSquare' must be populated if there is a photo for this person.
localPathSquare	No	string	The local path of the type_square photo for this person (e.g. /some/path/to/photo.png), if one exists. This is typically in the filecache. At least one of 'localPathBig' and 'localPathSquare' must be populated if there is a photo for this person.
localPathList	Yes	string	The local path of the photo for this person that is to be used in the contacts app list view (e.g. /some/path/to/photo.png). This is typically in the filecache. This is a cropped/scaled version of either 'localPathBig' or 'localPathSquare'.
listPhotoSource	Yes	string	type_big or type_square, depending on which one the list photo was cropped/scaled from.
photoIdBig	Yes	string	The DB8 id of the photo subobject that the localPathBig came from.
photoIdSquare	Yes	string	The DB8 id of the photo subobject that the localPathBig came from.
contactId	Yes	string	The DB8 id of the contact from which these photos came.
accountId	Yes	string	The DB8 id of the account which the contact referenced by contactId is a part of.
addressses	Yes	PersonPluralAddress array	De-duped addresses for all Contacts link to this person. Normalized by lowercasing.
urls	Yes	FavoritablePersonPluralField array	De-duped urls for all contacts linked to this person. Normalized by lowercasing.
Notes	Yes	string array	The notes for all contacts linked to this person.
birthday	Yes	string	The birthday of this person in the format yyyy-mm-dd (using 0000 when the year is unknown).
anniversary	Yes	string	The wedding anniversary of this person in the format yyyy-mm-dd (using 0000 when the year is unknown).
gender	Yes	string	The gender of this person.
relations	No	ContactPluralField array	De-duped relations for all Contacts link to this person.
reminder	Yes	string	The reminder text for this person.
ringtone	Yes	PersonalRingtone array	The ringtone that is associated with this person.

PersonName

Schema

{
   "normalizedFamilyName"      : string,
   "normalizedGivenName"       : string,
   "normalizedMiddleName"      : string,
   "normalizedHonorificPrefix" : string,   
   "normalizedHonorificSuffix" : string,   

}

Elements

Element	Required	Type	Description
normalizedFamilyName	No	string	The normalized family name of this Contact, or 'Last Name' in most Western languages.
normalizedGivenName	No	string	The normalized given name of this Contact, or 'First Name' in most Western languages.
normalizedMiddleName	No	string	The normalized middle name(s) of this Contact.
normalizedHonorificPrefix	No	string	The normalized honorific prefix(es) of this Contact, or 'Title' in most Western languages.
normalizedHonorificSuffix	No	string	The normalized honorifix suffix(es) of this Contact, or 'Suffix' in most Western languages.

PersonPluralAddress

Schema

{
   "normalizedStreetAddress" : string,
   "normalizedLocality"      : string,
   "normalizedRegion"        : string,
   "normalizedPostalCode"    : string,   
   "normalizedCountry"       : string                 
}

Elements

Element	Required	Type	Description
normalizedStreetAddress	No	string	The normalized full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information.
normalizedLocality	No	string	The normalized city or locality component. Normalized by lowercasing.
normalizedRegion	No	string	The normalized state or region component. Normalized by lowercasing.
normalizedPostalCode	No	string	The normalized zipcode or postal code component.
normalizedCountry	No	string	The normalized country name component. Normalized by lowercasing.

PersonPluralField

Schema

{   
    extends           : ContactPluralField,
    "normalizedValue" : string
}

Elements

Element	Required	Type	Description
normalizedValue	No	string	A normalized version of the 'value' property of this field. Used for indexes/searches.

PersonPluralIMAddress

Schema

{
    extends  : FavoritablePersonPluralField,
   "type"    : string,
   "label"   : string
}

Elements

Element	Required	Type	Description
type	Yes	string	A string representing the service this IM Address is valid on. Current values are: service_aim, service_google, service_irc, service_yjp, service_lcs, service_dotmac, service_icq, service_xmpp, service_msn, service_skype, service_qq, service_jabber, service_yahoo, and service_default.
label	No	string	The label of field for this instance, usually used to label the preferred function of the given contact information. Must be "label_work", "label_home", "label_other",and others as described in the schema for Contact

PersonPluralPhoneNumber

Schema

{
    extends    : FavoritablePersonPluralField
   "speedDial" : string
}

Elements

Element	Required	Type	Description
speedDial	Yes	int	A string consisting of a single uppercase letter representing the speed dial the user has set on this phone number.

PersonRingtone

Schema

{
   "name"     : string,
   "location" : string
}

Elements

Element	Required	Type	Description
name	Yes	string	The displayable name of the ringtone
location	Yes	string	The location on the filesystem where this ringtone is located.