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

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.