# 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 list 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.

For more information on JSON, see the following websites:

- JSON objects, values and format—http://www.json.org/
- JSON schemas—http://tools.ietf.org/html/draft-zyp-json-schema-02

Note: A primer on how JSON data objects are formatted is beyond the scope of this document—consult the two links above for more information. However, in brief:

- Curly brackets ('{', '}') are used to enclose objects.
- Angle brackets ('[', ']') are used to enclose arrays.
- Colons (":") are used as delimiters in name/value pairs.
- Quotes (") are used for string values. Numeric values do not require string.

## 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.
photos.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.
photos.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.
photos.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'.
photos.listPhotoSource | Yes | string | type_big or type_square, depending on which one the list photo was cropped/scaled from.
photos.photoIdBig | Yes | string | The DB8 id of the photo subobject that the localPathBig came from.
photos.photoIdSquare | Yes | string | The DB8 id of the photo subobject that the localPathBig came from.
photos.contactId | Yes | string | The DB8 id of the contact from which these photos came.
photos.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.