Reference Guide

Welcome, guest Sign In

My Projects
Tools & Services
APIs and Services
- Flickr
- Geo
- Mail
- Search
- Social
- Updates
- YAP
- YQL
Developer Tools
- Hadoop
- YUI
- YSlow
- View all »
Resources
- Blog
- YDN Theater
- Hack U

YDN Reference Guide

Prev — Updating individual contacts in the Address Book

Data Formats — Next

Chapter 3. Reference Guide

Data Representation

Address Book data referenced by Requests and Responses is represented by entities in either XML or JSON format.

Request and Response Entities

The following tables define how entities are represented by data structures in XML and JSON format. The name of the entity becomes the tag name in XML and the object property name in JSON.

Note

In the JSON representation, dashes (-) are replaced with underscores (_).

Table 3.1. Top-Level Request Entities

Entity	Meaning
`add-request`	Used with addContacts; contains Contacts to add and/or merge in the user's Address Book.
`sync-request`	Used with synchronize; contains Contact and Category update data.

Table 3.2. Top-Level Response Entities

Entity	Meaning
`error`	An error Response; see Error Reporting for more information.
`search-response`	Response to a searchContacts Request; contains matching contacts.
`cats-response`	Response to a getCategories Request; contains a list of categories.
`add-response`	Response to an addContacts Request.
`sync-response`	Response to a synchronize Request.

Table 3.3. Child Entities

Entity	Meaning
`contact`	A contact; carries its own metadata and contains fields.
`field`	Type of non-structured field or structured field. Each "type" of structured and unstructured field is also an entity name. See Field Types for more information. For a structured field, components are properties of that entity.
`category`	A Contact Category, referenced from contacts by the Category ID (`catid`).
`add-contact`	Contact addition event or command.
`remove-contact`	Contact removal event or command.
`update-contact`	Contact update event or command.
`address-book-reset`	Address book reset event; not allowed as a command.
`add-category`	Category addition event or command.
`remove-category`	Category removal event or command.
`rename-category`	Category rename event or command.
`add-field`	Field addition event or command; part of any kind of contact event. Examples: `add-name`, `add-email`
`update-field`	Field update event or command; part of any kind of contact event. Examples: `update-name`, `update-email`
`remove-field`	Field removal event or command; part of any kind of contact event. Examples: `remove-name`, `remove-email`
`remove-field`	Field removal command independent of the actual field type; part of any kind of contact event.
`add-to-category`	Category membership event or command; part of a contact or field event.
`remove-from-category`	Category membership event or command; part of a contact or field event.
`bucket`	A bucket of contacts; contains the first and the last contact (see Bucketing).
`success`	A short success Response used by the synchronize method (per-operation).
`error`	An error Response used by the addContacts and synchronize methods (per-operation).

Representing Fields

Fields can be one of two types: structured and unstructured.

Structured Fields

Structured fields contain sub-fields. The available structured fields are: name, address and birthday and anniversary.

Name Field

The name field is a structured field. At least one component must be non-empty.

Table 3.4. Name Field Sub-Field

Field	Meaning
`first`	First name of the Contact.
`middle`	Middle name of the Contact
`last`	Last name of the Contact.
`prefix`	Name prefix, such as Mr., Ms. or Dr.
`suffix`	Name suffix, such as Jr., or PhD.
`first-sound`	Sound of the first name; intended for Yahoo! Japan.
`last-sound`	Sound of the last name; intended for Yahoo! Japan.

Address Field

The address field is a structured type. It can contain the following sub-fields. At least one component must be non-empty.

Table 3.5. Address Field Sub-Field

Field	Meaning
`street`	The street, street number, apartment, etc.
`city`	City name
`state`	State or province name
`zip`	Zip or postal code
`country`	Country name

Birthday and Anniversary Fields

Birthday and Anniversary are structured fields. They must contain a valid date.

Table 3.6. Birthday and Anniversary Field Sub-Field

Field	Meaning
`day`	1 to 31
`month`	1 to 12
`year`	Optional. 1902 to 2037, or empty.

Updating structured fields

Note

When updating a structured field, such as a name or an address, specify all sub-fields in the update. To clear a sub-field, specify an empty value.

Unstructured Fields

Unstructured fields do not contain sub-fields.

Table 3.7. Unstructured Fields

Field	Meaning
`nickname`	Nickname of the Contact.
`email`	Email address of the Contact. Must contain an '@' character.
`yahooid`	Yahoo! ID
`otherid`	Other identifiers, such as ICQ, distinguished by flags.
`phone`	Phone number; use flags for type.
`jobtitle`	Job title
`company`	Company name
`notes`	Comments about the Contact
`link`	A URL
`custom`	A custom field, has an extra metadata attribute called `title`.

Field Flags

Zero or more flags can be combined with any field. Currently, no validation is performed to prevent conflicting flag combinations. You can have a y360 photo phone, a pager company or a blog anniversary.

However, at this time, the Address Book UI will not display fields with an unrecognized flag combination, nor is it possible to arbitrarily combine field flags with field types in the UI. Therefore only a few sensible combinations will be encountered in practice.

Table 3.8. Field Flags

`home`	`work`	`personal`	`mobile`	`fax`	`pager`	`yahoophone`	`aol`	`msn`	`jabber`	`dotmac`
`icq`	`google`	`skype`	`irc`	`qq`	`lcs`	`external`	`y360`	`photo`	`blog`	`ibm`

Field flags are represented as properties on the field, with the name of the flag becoming the name of the property and "true" becoming the value of the property, if present. Absence of the property implies absence of the flag.

Note

When updating a field using the synchronize method, you do not have to repeat the flags that the field already has. When an update does not specify flags for a field, the default behavior is to retain whatever flags the field has.

If you do specify flags in a field update when using the synchronize method, assigning the value "false" to a flag removes the specified flag from the field. For example, a phone can be changed from a home phone to a mobile phone with the following XML:

Or in JSON:

Note

If the field update operation above did not explicitly clear the home flag, the result would be a field with both the home and the mobile flags set.

Representing Categories

Categories (also known as Labels or Tags) are stand-alone entities that can be associated with Contacts and/or Fields. Categories are identified by Category ID.

As a convenience, the Address Book API also allows you to refer a to Category by either its ID or its name.

Note

Category names cannot be empty, and they cannot contain the following characters: slashes, @, colons, semi-colons, brackets, parenthesis, less-than or greater-than signs, spaces , commas, single or double quotes. For example, "Garfield" is a valid category name, but "Black Cat" or "O'Neill" are not.

Examples

The following example of a synchronize request demonstrates how categories can be referred to by either ID or name, whichever is more convenient:

{"type": "sync_request",
 "events": [{"type": "add_contact",
             "ctempid": "4D617474-204772-6F656E696E67",
             "fields": [{"first": "Matt",
                         "last": "Groening",
                         "type": "add_name"}],
             "categories": [{"type": "add_to_category", "data": "Directors"}]
            },
            {"type": "add_category", "data": "Actors"},
            {"type": "remove_category", "data": "Stars"},
            {"type": "remove_category", "catid": 11},
            {"type": "rename_category", "old_category": {"data": "Directors"},
                                        "new_category": {"data": "Producers"}},
            {"type": "rename_category", "old_category": {"catid": 8},
                                        "new_category": {"data": "Writers"}},
            {"type": "update_contact",
             "ctempid": "4D617474-204772-6F656E696E67",
             "fields": [{"data": "groening",
                         "type": "add_nickname"}],
             "categories": [{"type": "add_to_category", "catid": 8}]
            }
]}

Field Value Normalization

The Address Book server performs the following string operations on field values:

strips leading and trailing white-space characters
strips from a '<' to the next unquoted '>'
strips '<' and '>'
converts "&{" to "&{"
leaves a single space character in place of each sequence of stripped characters if no other space preceded the stripped sequence (for example, "a <b>b" becomes "a b", but "a<b>b" becomes "a b")
The following characters are escaped to HTML entities:
- < (less than) becomes "<"
- > (greater than) becomes ">"
- & (ampersand) becomes "&"
- ' (single quote) becomes "'"
- " (double quote) becomes """

If you want to display data in HTML, you do not need to do anything. If you want to use it in a non-HTML environment, you need to reverse the HTML-encoding above. Stripping is not reversible.

Chapter 3. Reference Guide

Data Representation

Request and Response Entities

Note

Representing Fields

Structured Fields

Name Field

Address Field

Birthday and Anniversary Fields

Updating structured fields

Note

Unstructured Fields

Field Flags

Note

Note

Representing Categories

Note

Examples

Field Value Normalization

Table of Contents