# Introduction

Entries in KDE address databases are stored in key-value-pairs with different data types. Every part of an address or personal in general is mapped to such a key-value-pair. For inter-application portability, the valid keys in such a key-value-map need to be defined. This page gives an overview over all field names and types used by KDE address book entries:

Field Key | Literal Field Name | Field Meaning | Data Type | Encoding
X-First_Name | First Name | The first name of the person. | kde-string | Unicode string
X-Middle_Name | Middle Name | The middle name of the person. | kde-string | Unicode string
X-Last_Name | Last Name | The last name of the person. | kde-string | Unicode string
X-Org | Organization |  |  |
X-Department | Department |  |  |
X-OfficeLocation | Office |  |  |
X-Role | Role |  |  |
X-Headline_1 | (none) | The description for the address ("Home", "Weekend", whatever). |  |
X-Street_1 | Street | Street for the first address. |  |
X-ZIP_1 | Zip/Postal Code |  |  |
X-City_1 | City/Town |  |  |
X-Country_1 | Country |  |  |
X-State_1 | State/Province |  |  |
(repeat X-Headline to X-State 4 times to get five addresses) |  |  |  |
X-Title | Title | Titles are academic degrees, for example. |  |
X-Rank | Rank | Military or police officers ranks, also used on ships. |  |
X-Birthday | Birthday |  |  |
X-Comment | (None) | An optionally free-form note about the person. |  |
X-Email_1 | Email Address 1 | The first email address. Up to 5 are supported. |  |
(repeat X-Email _X four times) |  |  |  |
X-Talk_1 | Talk Address 1 | The first email address. Up to 5 are supported. |  |
(repeat X-Talk_X four times) |  |  |  |
X-URL_1 | Home Page Address 1 |  |  |
(repeat X_URL_X four times) |  |  |  |
X-Telephone_1 | Telephone Number 1 |  |  |
(repeat X-Telephone_X four times) |  |  |  |

The following notes should guide through the columns of the table.

# Field Key

The field key is used to find the value. Thus, it needs to be identifying. In every entry, all keys may be inserted only one time (in STL terms, the entries are maps, not sets). As a guideline, all valid C++ identifiers may be used as field keys.

# Literal field Name

This values have been defined to make sure each application uses the same names for different fields. This should make it easier for the applications users to find what they look for.

# Some Notes

This notes might be removed after the field names are standardized.

## Number of Addresses

In this overview, the number of addresses is no more fixed by a special value (like MAX_ADDRESSES in the former class "Entry"). There are simply (currently) 3 fields named X-Street_1, X-Street_2, and X-Street_3.
Also, addresses, by now, do not have types like business, home, or other. It would probably be a good idea to give some patterns when entering the headline, but allow the user to select other names, too. This way addresses may be sorted in other categories than the programmer is able to anticipate :-)

## Telephone Numbers

I would opt for the following way to store telephone (and related) numbers:

- Define the types, for example, "Home", "Cellular", "Fax", "Other".
- Store each number as a combination of type and number. Could be done as a string, like "FAX: 0123456789".

The apps would have to parse this and find the type.

## The very special Fields

It is a matter of agreement what fields are declared to be a standard and what would be application-specific extensions.
I chose it the following way: Everything that is part of the persons attributes and that we already thought of is a standard field, and everything completely unusable by other applications must be an application-specific extension.
The reason is explainable by the following examples:

- The rank field is very special. But if two applications A-Book and B-Book store the rank of a person, it would be nonsense if one stores "A-Book-Rank", and the other reads "B-Book-Rank".
- Consider the pilot conduit interfacing the addressbook applications to the pilots addressbook. Here, "Pilot-Conduit-EntryID" would not make any sense to A-Book or B-Book. This is definitly application specific.

As a consequence, we will have to add more attributes that we currently not think of later. But this should be no problem.