# KAB2 format definition information

## Introduction

KAB2 uses format definitions. These allow key name -> value type mappings to be created. Note that this is not key -> value mapping. It is the name of the key and the data type of the value which we are concerned with.

## Why use format definitions ?

Most addressbooks use a fixed format definition. For example, the vCard specification defines a set of field names with strictly defined value storage. KAB1 does the same. While this is fine for a very simple addressbook, users often wish to extend the addressbook format, storing different information to that which was initially envisaged as being necessary by the format author.

While it is possible to allow for extensions through 'extra' fields, this is not an ideal solution to the problem. KAB2 tries to address the problem by providing no fixed format, rather the format may be specified freely.

## Issues

One side-effect of allowing arbitrary value types is that the front-end may not know how to present some values to the user. For example, the user may wish to store images in a format which the front-end has no handler for.

There are many possible solutions to the problem stated above. One is to provide a value-storage specification mechanism within the addressbook format definition. This, however, would quickly become extremely complex and would still require convoluted mechanisms within the front-end to handle hints from the format definition as to how value types should be rendered.

It is my opinion that keeping the format definition simple and leaving rendering decisions to the front-end is the wisest route. Modern desktop applications usually have some support for embedding or launching viewers for arbitrary mime types.

Mime types for which a handler cannot be found can be dealt with in a sensible fashion. For example, a web browser will usually ask the user for a program which can display an image whose format it does not recognise.

While leaving data format handling to the front-end is convenient to the writer of the format definition mechanism, it is still possible to provide a reasonable system for handling enumerated types and lists. This is what KAB2 attempts to do.

## Storage

Format definitions are stored by KAB2 using a class called FormatDefinition. A FormatDefinition holds FieldFormat objects, each of which specifies the key, caption, value data type, and other meta-information about a 'field'.

The FormatDefinition class is easy to use for the programmer, but definitions must also be editable by the user. This suggests that a GUI editor for definitions would be useful, but does not address the problem of no GUI being available, nor does it allow for a platform-independent storage format.

To address these issues, format definitions may be stored in XML. This allows editing on the most basic of equipment, ensures that the format will be readable and understandable by a reasonably capable user, and deals with transmission, platform dependence and storage details at once.

### Example XML format definition file:

    <?xml version="1.0" encoding="UTF-8"?>

    <!DOCTYPE kab_format>

    <kab-definition name="definition name">

      <field
        name="name"
        caption="Full name"
        unique="true"
        mimetype="text/UCS-2"
      />

      <field
        name="homePage"
        caption="Home page"
        unique="false"
        mimetype="text/uri"
      />

      <field
        email="email"
        caption="Email address"
        unique="false"
        mimetype="address/rfc822"
      />

    </kab-definition>

More text to go here later...