KEP-0013.txt
Georg Greve
greve at kolabsys.com
Mon Aug 29 13:30:57 CEST 2011
KEP-0013.txt | 239 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 239 insertions(+)
New commits:
commit 17e4b65c5e07d6851412249c9d027dced9580bd4
Author: Georg Greve <greve at kolabsys.com>
Date: Mon Aug 29 13:30:40 2011 +0200
First draft of contact object update KEP
diff --git a/KEP-0013.txt b/KEP-0013.txt
new file mode 100644
index 0000000..a0e9da5
--- /dev/null
+++ b/KEP-0013.txt
@@ -0,0 +1,239 @@
+{{kep
+ |number=13
+ |ticketnumber=
+ |title=Update 'contact' object
+ |author=Georg Greve
+ |author_email=greve at kolabsys.com
+ |status=draft
+ |type=design
+ |creation_date=
+ |obsoleted_by=
+ |related=
+}}
+
+
+== Abstract ==
+
+This Kolab Enhancement Proposal (KEP) <ref name"kep">[[KEP:1]] Bootstrapping the KEP process</ref> defines part of a changeset applied against Kolab XML version 1.0 of Kolab Format 2.0 to update the XML object 'contact' to address a wide range of issues which are detailed in the [[#Issues|Issues]] subsection, below.
+
+== Update to the XML Format ==
+
+The 'contact' XML object of the resulting Kolab Format after application of this KEP retains the standard common fields. Object specific fields that remain unaffected by this KEP are:
+
+ <body>(string, default empty)</body>
+ <name>
+ <given-name>(string, default empty)</given-name>
+ <middle-names>(string, default empty)</middle-names>
+ <last-name>(string, default empty)</last-name>
+ <full-name>(string, default empty)</full-name>
+ <initials>(string, default empty)</initials>
+ <prefix>(string, default empty)</prefix>
+ <suffix>(string, default empty)</suffix>
+ </name>
+ <nick-name>(string, default empty)</nick-name>
+ <gender>(string, default empty)</gender>
+ <birthday>(date, no default)</birthday>
+ <anniversary>(date, no default)</anniversary>
+ <picture>(string(attachment filename), default empty)</picture>
+ <profession>(string, default empty)</profession>
+ <free-busy-url>(string, default empty)</free-busy-url>
+ <latitude>(float, no default)</latitude>
+ <longitude>(float, no default)</longitude>
+ <language>(string, default empty)</language>
+
+==== TODO: Need definition / clarification ====
+* language: What is stored in this field? ISO Code set of languages, comma-separated?!
+
+The remaining object specific fields are redefined by this KEP as follows:
+
+ <!--- Fields with organisational affiliation --->
+ <org label="(string, no default)">
+ <organization>(string, default empty)</organization>
+ <x-logo>(string(attachment filename), default empty)</x-logo>
+ <department>(string, default empty)</department>
+ <office-location>(string, default empty)</office-location>
+ <job-title>(string, default empty)</job-title>
+ {<phone type="<phonetype>" label="(string, default empty)">(string, default empty)</phone>}
+ {<email label="(string, default empty)" displayname="(string, default empty)">(string, default empty)</email>}
+ {<web-page label="(string, default empty)">(string, default empty)</web-page>}
+ {<im-address label="(string, default empty)" app="<application type>">(string, default empty)</im-address>}
+ {<address lanel="(string, default empty)">
+ <type>(string, default home)</type>
+ <street>(string, default empty)</street>
+ <locality>(string, default empty)</locality>
+ <region>(string, default empty)</region>
+ <postal-code>(string, default empty)</postal-code>
+ <country>(string, default empty)</country>
+ </address>}
+ <manager-name>(string, default empty)</manager-name>
+ <assistant>(string, default empty)</assistant>
+ </org>
+
+ <!--- Fields without organisational affiliation --->
+ <spouse-name>(string, default empty)</spouse-name>
+ <children>(string, default empty)</children>
+
+ {<phone type="<phonetype>" label="(string, default empty)">(string, default empty)</phone>}
+ {<email label="(string, default empty)" displayname="(string, default empty)">(string, default empty)</email>}
+ {<web-page label="(string, default empty)">(string, default empty)</web-page>}
+ {<im-address label="(string, default empty)" app="<application type>">(string, default empty)</im-address>}
+ {<address lanel="(string, default empty)">
+ <type>(string, default home)</type>
+ <street>(string, default empty)</street>
+ <locality>(string, default empty)</locality>
+ <region>(string, default empty)</region>
+ <postal-code>(string, default empty)</postal-code>
+ <country>(string, default empty)</country>
+ </address>}
+
+ <!--- Preferences --->
+ <preferred>
+ <email>(string, default empty)</email>
+ <web-page>(string, default empty)</web-page>
+ <im-address>(string, default empty)</im-address>
+ <address>(string, default empty)</address>
+ <key type="[OPGP,SMIME]" sign="[always,never,ifpossible]" encrypt="[always,never,ifpossible]">(string, default empty)</key>
+ </preferred>
+
+with the following specification of field values:
+* '''label''': Internal descriptive label to refer to entry, e.g. for organization this could be "Parent's Company" "Work" "Day-Job" "Voluntary Engagement", for phone numbers it could be "German Mobile", "Swiss Mobile", "Private" and so on
+* '''x-logo''': File name of logo of company/organization
+* '''phone''': Phone number/URL, with attributes
+** '''label''': see above, a descriptive name for this value, e.g. "Work", "Direct", "Assistant", "Mobile"
+** '''type''': a string value of comma separated '''capabilities''' with the following capabilities pre-defined: 'speech', 'mobile', 'fax', 'voip', 'video', 'chat'
+* '''web-page''': Field can appear numerous times, including outside organizational context, provides URL to web page;
+* '''im-address''': Field can appear numerous times, including outside organizational context, provides address of chat/instant messenger account, attribute 'app' defines the type of IM account
+* '''preferred''': Stores preference for various entries and crypto settings for this person. The fields refer to the labels or values of records in this contact. An empty field or a value that does not match a label or value of a field of this type '''SHALL''' be interpreted as 'no preference'
+
+
+==== TODO: Need definition / clarification ====
+* fields referring to other people - ideally linking to other records, how? use email as identifier?
+* find out what the x-kde-type means (see example in [[#Issues|Issues]])
+
+
+== Upgrade Path ==
+
+The changes are inevitably breaking backward compatibility.
+
+So this KEP should be applied as part of a breaking changeset in order
+to keep the disturbance to a minimum.
+
+== Rationale ==
+
+=== Issues ===
+
+The issues this KEP is seeking to address are best explained using a concrete example. The following represents actual output from creating an address book entry with KDE PIM of KDE 4.7. This is not an official reference client, but that is of no consequence for the points that shall be demonstrated. Consider the following data set:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <contact version="1.0">
+ <product-id>KAddressBook 3.3, Kolab resource</product-id>
+ <uid>WhX99dWHD9</uid>
+ <body>Notes for the Test Contact</body>
+ <last-modification-date>2011-08-29T08:28:19Z</last-modification-date>
+ <sensitivity>public</sensitivity>
+ <name>
+ <given-name>Test</given-name>
+ <last-name>Tester</last-name>
+ <full-name>Test Tester</full-name>
+ </name>
+ <organization>Test Company</organization>
+ <im-address>jabber address</im-address>
+ <department>Testing</department>
+ <profession>Certified Supertester</profession>
+ <job-title>CIT</job-title>
+ <manager-name>Boss of Tester</manager-name>
+ <assistant>Assistant of Tester</assistant>
+ <nick-name>The Tester</nick-name>
+ <x-logo>kolab-logo.png</x-logo>
+ <phone>
+ <type>mobile</type>
+ <number>first mobile</number>
+ </phone>
+ <phone>
+ <type>mobile</type>
+ <number>second mobile</number>
+ </phone>
+ <phone>
+ <type>mobile</type>
+ <number>third mobile</number>
+ </phone>
+ <email>
+ <display-name>Test Tester</display-name>
+ <smtp-address>4 at email.test</smtp-address>
+ </email>
+ <email>
+ <display-name>Test Tester</display-name>
+ <smtp-address>1 at email.test</smtp-address>
+ </email>
+ <email>
+ <display-name>Test Tester</display-name>
+ <smtp-address>2 at email.test</smtp-address>
+ </email>
+ <email>
+ <display-name>Test Tester</display-name>
+ <smtp-address>3 at email.test</smtp-address>
+ </email>
+ <email>
+ <display-name>Test Tester</display-name>
+ <smtp-address>5 at email.test</smtp-address>
+ </email>
+ <address>
+ <type>home</type>
+ <x-kde-type>80</x-kde-type>
+ <street>Homestreet</street>
+ <locality>Hometown</locality>
+ <region>Homeregion</region>
+ <postal-code>12345</postal-code>
+ <country>Germany</country>
+ </address>
+ <address>
+ <type>business</type>
+ <x-kde-type>32</x-kde-type>
+ <street>Workstreet</street>
+ <locality>Worktown</locality>
+ <region>Workregion</region>
+ <postal-code>98765</postal-code>
+ <country>Germany</country>
+ </address>
+ <address>
+ <type>home</type>
+ <x-kde-type>16</x-kde-type>
+ <street>Second Homestreet</street>
+ <locality>Second Hometown</locality>
+ <region>Second Homeregion</region>
+ <postal-code>1265354</postal-code>
+ <country>Germany</country>
+ </address>
+ <preferred-address>home</preferred-address>
+ <x-custom value="2001-01-01T12:01:00" app="" name="930a145e-e9e0-402b-868a-21b6820a9e8c"/>
+ <x-custom value="alwaysIfPossible" app="" name="CRYPTOENCRYPTPREF"/>
+ <x-custom value="openpgp/mime" app="" name="CRYPTOPROTOPREF"/>
+ <x-custom value="alwaysIfPossible" app="" name="CRYPTOSIGNPREF"/>
+ <x-custom value="aim address" app="messaging/aim" name="All"/>
+ <x-custom value="icq address" app="messaging/icq" name="All"/>
+ <x-custom value="jabber address" app="messaging/xmpp" name="All"/>
+ </contact>
+
+Apparent issues when comparing this to the specification of version 1.0 Kolab XML objects in Kolab Format 2.0 are:
+* Kolab Format 2.0 only allows a single instance for instant messenger, although most people have quite a few, which Kontact worked around by storing the data in x-custom fields;
+* Kolab Format 2.0 does not foresee storage for the company logo, which Kontact stores in a 'x-logo' field which is undefined;
+* Kolab Format 2.0 does not foresee that many people have multiple roles & affiliations;
+* Kolab Format 2.0 only allows a single instance of the 'mobile' phone type. Kontact has ignored this to save three mobile phone numbers, which is a good thing to do, because having more than one mobile phone number is quite common these days;
+* Kolab Format 2.0 states: ''"The Kontact and Horde address books have the notion of a preferred email address. This could be done by a bool on the emails or a separate tag like for preferred address."'' While clients '''could''' have done it this way, Kontact clearly did not. Instead it resorted the email addresses to put the preferred one on top. There should be a clear and canonical way of handling this;
+* Kolab Format 2.0 is not explicit on whether or not multiple addresses of one type, e.g. 'home' are allowed or forbidden, so Kontact allows to create and store them. The 'preferred-address' field then refers to the '''type''' of address, which would suggest that only one address per type was foreseen because like this it is not clear '''which''' home address is preferred. And finally there is a field 'x-kde-type' which is undefined in the Kolab Format 2.0 and thus cannot be supported by other clients;
+* Kolab Format 2.0 does not know crypto preferences even though cryptography is one of the unique advantages that the Kolab Groupware Solution has to offer;
+* Kolab Format 2.0 only supports one web page field even though most people have multiple profiles & pages;
+* The fields referring to other people, possibly other records in the address book, are string fields only and thus fail to semantically link the data;
+* There is no coordinated way for clients to share information on more modern social media applications, e.g. Identi.ca, Facebook or Twitter, which did not exist when the specification was written.
+
+All of the above need to be resolved by this KEP.
+
+
+
+== References ==
+
+{{Reflist}}
+
+== Copyright ==
+
+This document has been placed in the public domain.
More information about the commits
mailing list