summaryrefslogtreecommitdiff
path: root/KEP-0013.txt
blob: a319bcbf735d3a46efc84016ab154459ea4141b8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
{{kep
 |number=13
 |ticketnumber=
 |title=Update 'contact' object
 |author=Georg Greve
 |author_email=greve@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?
* '''x-kde-type''' was introduced as part of a hotfix for Issue #1706<ref name="x-kde-type">Kolab Issue #1706: [https://issues.kolab.org/issue1706 addressbook: real address type is broken)]</ref> and thus found its way into the KDE SVN<ref name="x-kde-type-svn">KDE: [http://websvn.kde.org/branches/kdepim/enterprise/kdelibs/kabc/address.h?view=markup#l78 WebSVN]</ref> but was never documented. Question: Do we still need this?

== 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@email.test</smtp-address>
  </email>
  <email>
   <display-name>Test Tester</display-name>
   <smtp-address>1@email.test</smtp-address>
  </email>
  <email>
   <display-name>Test Tester</display-name>
   <smtp-address>2@email.test</smtp-address>
  </email>
  <email>
   <display-name>Test Tester</display-name>
   <smtp-address>3@email.test</smtp-address>
  </email>
  <email>
   <display-name>Test Tester</display-name>
   <smtp-address>5@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'<ref name="x-kde-type" /><ref name="x-kde-type-svn" /> 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.