summaryrefslogtreecommitdiff
path: root/KEP-0017.txt
blob: 73841e68549fb698c519eca39f467c3fc2467f4e (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
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
{{kep
 |number=17
 |ticketnumber=
 |title=Kolab XML Format 3.0
 |author=Christian Mollekopf
 |author_email=mollekopf@kolabsys.com
 |status=draft
 |type=design
 |creation_date=2011-12-12
 |obsoleted_by=
 |obsoletes=2,3,8,13
 |related=9
}}



== Abstract ==

[[KEP:1]]<ref name="kep1">[[KEP:1]] Bootstrapping the KEP process</ref> defines a new Kolab XML Version 3.0 for the Kolab Format 3.0 specification. This format '''SHALL''' be canonical from Kolab Version 3.0 and upward.

This KEP incorporates previous KEPs that have addressed issues in the Kolab Format, most importantly [[KEP:2]]<ref name="kep2">[[KEP:2]] Modification of datetime: store local time, add 'tz' attribute</ref>, [[KEP:9]]<ref name="kep9">[[KEP:9]] Configuration_storage_in_XML_objects</ref>. <!--, [[KEP:12]]<ref name="kep12">[[KEP:12]] Color configuration storage for resources and categories</ref> and [[KEP:16]]<ref name="kep16">[[KEP:16]] Storage of dictionary entries</ref>.//-->

Due to reasons outlined in the rationale at the end of this KEP, the Kolab XML format is re-based on the recently released {{rfc|6321}} <ref name="rfc6321">{{rfc|6321|title=XML Representation of iCal (xCal)}}</ref> and {{rfc|6350}} <ref name="rfc6351">{{rfc|6351|title=XML Representation of vCard (xCard)}}</ref> standards. Only where no suitable standards exist does this KEP specify updates on the Kolab Format Version 2.0 definition of these objects.

It is intended to work with international processes wherever possible to ensure that these objects will eventually be addressed through widely adopted standards, as well.

== Notation ==

XML Objects are described using the [http://relaxng.org/compact-20021121.html Relax NG compact syntax]<ref name="relaxng">[http://relaxng.org/compact-20021121.html] Relax NG compact syntax </ref>.

Pattern restriction of single string values are according to [http://www.w3.org/TR/xmlschema11-2/#rf-pattern]<ref name="xsdPattern">[http://www.w3.org/TR/xmlschema11-2/#rf-pattern] XSD Pattern</ref>.

== General Considerations ==

Kolab XML is based on XML Version 1.0.

Semantics '''SHALL''' be according to the respective RFCs unless specified different by this KEP.

The Kolab Format will consist of a subset of {{rfc|6321}} and {{rfc|6351}} features complemented by application behaviour specifications and additional specifications which are lacking in the RFCs.

That initial subset is defined as the necessary set of fields and semantics required to map the functionality of Kolab Format 2.0 in {{rfc|6321}} / {{rfc|6351}} compliant form plus any additions defined in this KEP.

An implementation of the Kolab XML Format '''SHALL''' be able to understand all properties defined in the respective format description and '''SHALL NOT''' degrade any property. In any case it '''SHALL''' preserve the semantic meaning of the property.

The order of the elements is '''REQUIRED''' unless otherwise specified using the Relax NG Format description

The 'X-Kolab-Type' field which is defined for every Kolab XML Object '''SHALL''' be used as {{rfc|2822}} <ref name="rfc2822">{{rfc|2822|title=Internet Message Format}}</ref> message header of the encapsulating email object.

== Kolab XML Objects ==

A Kolab XML Object is a container for the various data types the Kolab Groupware Suite stores.

Currently this includes:
* [[#Event]]
* [[#Todo]]
* [[#Journal]]
* [[#Contact]]
* [[#Distribution List]]
* [[#Configuration]]

=== Properties ===

The following properties apply to all Kolab Objects. The individual datatype definitions of the objects '''MUST''' be followed.

==== Kolab XML Version ====

  value-version = ( [[#String]] )

''The version number identifies the Kolab XML Format specification which was used to write the file.''

The version number '''MUST''' be according to [[#Version number]]

This property '''MUST''' be updated whenever an object is modified.

==== UID ====

  value-uid = ( [[#String]] )
  
  text-uid = element text { [[#String]] }
  
  uri-uid = element uri { [[#URI]] }  


''A UID uniquely identifying the Kolab XML Object.''

The UID '''SHALL''' be globally unique.

The global uniqueness of a UID '''SHOULD''' be achieved by following the provisions set forth in {{rfc|4122}}<ref name="rfc4122">{{rfc|4122|A Universally Unique IDentifier (UUID) URN Namespace}}</ref>.

The UID '''MUST NOT''' be changed after initial creation of the object.

A UID in the uri format (uri-uid), '''MUST''' use the URN namespace described in {{rfc|4122}}<ref name="rfc4122">{{rfc|4122|A Universally Unique IDentifier (UUID) URN Namespace}}</ref>.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.4.7 section-3.8.4.7]
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.7.6 section-6.7.6]

==== Creation date ====

  value-creation-date = ( [[#Date-Time]] )

''The date-time timestamp when the object was created.''

The date-time '''MUST''' be in UTC.

This property '''MUST NOT''' be changed after initial creation of the object.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.7.1 section-3.8.7.1]

==== Last modification date ====

  value-lastmodified-date = ( [[#Date-Time]] )

''The date-time timestamp when the object was last modified.''

The date-time '''MUST''' be in UTC.

This property '''MUST''' be updated whenever an object is modified.

{{note|xCard|Note that xCard uses a timestamp element instead of a date-time element for the "ref" property.}}

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.7.2 section-3.8.7.2]
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.7.4 section-6.7.4]

==== Product ID ====

  value-productid = ( [[#String]] )
  
  property-prodid = element prodid {
    element text { value-productid }
  }

''An identification of the client who has written out the last version of the object.''

The product-id '''SHOULD''' uniquely identify the client and the format implementation, including version number, which last modified the object.

This property '''MUST''' be updated whenever an object is modified.

This property's primary purpose is debugging.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.7.3 section-3.7.3]
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.7.3 section-6.7.3]

==== Classification ====

  value-classification = ( "PRIVATE"|"CONFIDENTIAL"|"PUBLIC" )

''The classification gives an indication of the (security) classification of the object.''

The classification '''MUST''' be one of "PRIVATE", "CONFIDENTIAL" and "PUBLIC".

* "PRIVATE": The object contains private information and is meant for the owner of the object only.
* "CONFIDENTIAL": The object contains confidential information and is meant for an authorized group only.
* "PUBLIC": The object doesn't contain any private/confidential information and doesn't have to be handled with extra care.

This property serves mainly the purpose of giving the user an indication how the contained information should be handled.

Client implementations '''MAY''' behave differently depending on the classifcation of the object. The implementation '''SHOULD''' give the user an indication of the classification so he can act accordingly.
If the "Classification" property is absent, the client '''SHALL''' behave as if the classification was "PUBLIC".

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.1.3 section-3.8.1.3]

{{note|Implementation note: Classification/Sensitivity|This property was renamed from Sensitivity to Classification to reuse the wording used in RFC5545}}
{{note|xCard Kolab V2 compatibility|xCard doesn't support this notion and the property was dropped for the Contact/Distribution-List Objects}}

==== Categories ====

  value-category = ( [[#String]] )
  
  category-hierarchy = value-category("\"value-category)*
  
  property-categories = (
    element text { category-hierarchy } +
  )

''A simple text tag used to categorize the object.''

Category tags are mostly used to group objects into categories.

The tags '''MAY''' use a hierarchy by prepending parent tags using '\' (Backslash: U+005C) as delimiter.

A value-category '''MUST NOT''' contain a '\' (Backslash: U+005C).

Defining a single category-hierarchy '''SHALL''' be sufficient to define all categories which are part of the hierarchy, but the object "MUST" only get the whole category-hierarchy as category and not each indvidual value-category.

A category '''SHALL''' be identifieable by string comparison. The whole category-hierarchy '''MUST''' be compared.

{{note|Example|"parent\child" would indicate a parent-child relationship between "parent" and "child". This defines the categories "parent" and "parent\child". Note that the "child" category of "parent2\child" is not the same as "parent\child". Note also that unless "parent" is also explicitly added to the categories list the object has only the "parent\child" category and not the "parent" category.}}

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.1.2 section-3.8.1.2]
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.7.1 section-6.7.1]

{{note|Implementation note: Structured Tags|In the future the might be a need for structured tags consiting of type, identifier, display name (and possibly a hierarchical relation). This is however not currently used (except for nepomuk) and was therefore not implemented. For the current needs this would have been a overengineering solution. Structured tags can be introduced at a later stage without rendering this property useless.}}
{{note|Implementation note: Hierarchy|The hierarchy is not build using xml element nesting (such as in the category configuration) for compatibility with the used RFCs.}}

=== xCal based objects ===

  element icalendar {
    element vcalendar {
      element properties {
        element prodid { [[#Product ID]] },
        element version { [[#xCal Version]] },
        element x-kolab-version { [[#Kolab XML Version]] },
      },
      element components {
        element vevent { [[#Event|event]] } |
        element vtodo { [[#Todo|todo]] } |
        element vjournal { [[#Journal|journal]] },
        [[#Recurrence exception|recurrence-exception]] *
      }
    }
  }

All xCal based objects '''MUST''' fully comply to {{rfc|6321}}<ref name="rfc6321" />.

Each Kolab XML Object '''MUST''' contain exactly one main todo/event/journal object stored according to {{rfc|6321}}<ref name="rfc6321" />.
It '''MAY''' contain additionally a number of [[#Recurrence exception|Recurrence exceptions]] which '''MUST''' be of the same type as the main object.

VTimezone '''MUST NOT''' be used. Instead timezone identifiers according to [[#Timezone Identifier]] '''MUST''' be used.

In the following sectopm "incidence" refers to an event, todo or journal entry.
==== Properties ====

===== xCal Version =====

  property-version = element version {
    element text { "2.0" }
  }

''The xCal version number.''

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.7.4 section-3.7.4]

===== Related-to =====

  property-relatedto = element related-to {
    [[#UID|text-uid]]
  }

''Parent relationship of the todo.''

This property '''MUST''' specify a "Parent" relationship. Other relations '''MUST NOT''' be used.

A "Parent" relation '''SHALL''' specify the parent todo of this todo.

The value '''MUST''' contain the UID of another object which has a parent relationship to this object.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.4.5 section-3.8.4.5]

===== Start date =====

  property-dtstart = element dtstart {
    element parameters {
      [[#xCal Timezone Identifier|xcal-tzid]] ?
    } ?,
    [[#xCal Date-Time|xcal-date-or-date-time]]
  }

''Start date of the event/todo/journal entry.''

"All-Day" Events are indicated by using the date-only format for the dtstart property.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.2.4 section-3.8.2.4]

===== End date =====

  property-dtend = element dtend {
    element parameters {
      [[#xCal Timezone Identifier|xcal-tzid]] ?
    } ?,
    [[#xCal Date-Time|xcal-date-or-date-time]]
  }

''End date of the event/journal entry.''

The value type of this property '''MUST''' be the same as the [[#Start date]] property, and its value '''MUST''' be later in time than the value of the [[#Start date]] property.  Furthermore, this property '''MUST''' be specified as a date with local time if and only if the [[#Start date]] property is also specified as a date with local time.

This property '''MUST NOT''' be specified if an [[#Incidence Duration]] was specified.

{{note|Example: Full-Day Event|To indicate an event which takes one full day, the dtend must be a day later than dtstart. dtstart=20110208 dtend=20110209 results in an Event taking all of 20110208.}}

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.2.2 section-3.8.2.2]

===== Incidence Duration =====

  property-duration = element duration {
    element duration { [[#Duration]] }
  }

''Duration of the event/journal entry.''

This property '''MUST NOT''' be specified if an [[#End date]] was specified.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.2.5 section-3.8.2.5]

===== Due date =====

  property-due = element due {
    element parameters {
      [[#xCal Timezone Identifier| xcal-tzid]] ?
    } ?,
    [[#xCal Date-Time|xcal-date-or-date-time]]
  }

''Date until the todo should be completed.''

The value type of this property '''MUST''' be the same as the [[#Start date]] property, and its value '''MUST''' be later in time than the value of the [[#Start date]] property.  Furthermore, this property '''MUST''' be specified as a date with local time if and only if the [[#Start date]] property is also specified as a date with local time.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.2.3 section-3.8.2.3]

===== Transparency =====

  property-transp = element transp {
    element text { "OPAQUE" | "TRANSPARENT" }
  }

''Specifies, if an event is free/busy-relevant.''

* "OPAQUE": The event is visible in freebusy time searches.
* "TRANSPARENT": The event is invisible in freebusy time searches.

If not specified this property '''SHALL''' default to "OPAQUE".
Events with the transparency set to "TRANSPARENT" '''MUST NOT''' be used in any free/busy time searches/generation.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.2.7 section-3.8.2.7]

===== Sequence =====

  property-seq = element sequence {
    element integer { [[#Integer|xsd:integer]] }
  }

''The sequence number of the object.''

This property '''MUST''' be increased by one everytime the object is modified.

The initial value of this property '''SHALL''' be zero.

This property is used primarily for iTip message handling.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.7.4 section-3.8.7.4]
* {{rfc|5546}} [https://tools.ietf.org/html/rfc5546#section-2.1 section-2.1]

===== Recurrences =====

The complete set of recurrences '''MUST''' be derived using the [[#Start date]], [[#Recurrence rule]], [[#Recurrence date]] and [[#Exception date]] properties.

If no [[#Start date]] is available (i.e. in a todo), the recurrence '''SHALL''' be ignored.

The following procedure '''SHALL''' be used:
# Derive recurrence set from [[#Recurrence rule]] and [[#Start date]]
# Add further recurrence dates contained in [[#Recurrence date]]
# Remove exceptions from [[#Exception date]]
# Apply changes from [[#Recurrence exception|Recurrence exceptions]] matching a [[#Recurrence ID]] stored in the same Kolab XML Object

Duplicate recurrences (same start-date) '''MUST''' be ignored and considered as a single occurence.

The [[#Start date]] is part of the complete recurrence set.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.5.3 section-3.8.5.3].

{{note|Obsoletion of KEP 3|This obsoletes [[KEP:3]]<ref name="kep3">[[KEP:3]] Introduction of subevent sub-tag for exclusion from recurrence</ref> as those requirements are now fullfilled by the [[#Exception date]] and [[#Recurrence ID]] properties.}}

====== Recurrence exception ======

  recurrence-exception = (
    element vevent { [[#Event|event]] } |
    element vtodo { [[#Todo|todo]] }
  )

''A recurrence exception overwrites properties of the base object in a specific recurrence of an event/todo.''

A recurrence exception can be identified as exception by the presence of the [[#Recurrence ID]] property which '''MUST''' be specified on recurrence exceptions and '''MUST NOT''' be specified on the base object.

A recurrence exception '''MUST''' be of the same type as the base object.

A recurrence exception '''SHALL''' only specify what should be changed from the base object.

A recurrence exception '''MUST NOT''' define a new recurrence rule using any of [[#Recurrence rule]], [[#Recurrence date]], [[#Exception date]]

Recurrence exceptions '''MUST''' be defined in the same Kolab XML Object as the base object.

The [[#UID]] parameter of the recurrence exception '''MUST''' match the [[#UID]] parameter of the base object.

{{note|Implementation note|By not allowing recurrences to be defined on exceptions it is not possible to apply the same exception to multiple recurrences. Since this feature is not used currently it seems sensible to not allow this.}}


====== Recurrence rule ======

  type-weekday = ("SU" | "MO" | "TU" | "WE" | "TH" | "FR" | "SA")
  
  byday-pattern = ([[#Integer|xsd:integer]]?type-weekday)
  
  property-rrule = element rrule {
    element recur {
      element freq { "SECONDLY" | "MINUTELY" | "HOURLY" | "DAILY" | "WEEKLY" | "MONTHLY" | "YEARLY" },
      ( element until { [[#xCal Date-Time|xcal-date-time]] } | element count { [[#Integer|xsd:positiveInteger]] })?,
      element interval { [[#Integer|xsd:positiveInteger]] }?,
      element bysecond { [[#Integer|xsd:positiveInteger]] }*,
      element byminute { [[#Integer|xsd:positiveInteger]] }*,
      element byhour { [[#Integer|xsd:positiveInteger]] }*,
      element byday { byday-pattern }*,
      element bymonthday { [[#Integer|xsd:integer]] }*,
      element byyearday { [[#Integer|xsd:integer]] }*,
      element byweekno { [[#Integer|xsd:integer]] }*,
      element bymonth { [[#Integer|xsd:positiveInteger]] }*,
      element bysetpos { [[#Integer|xsd:integer]] }*,
      element wkst { type-weekday }?
    }
  }

''Description of a recurring incidence.''

The recurrence rule '''SHALL''' be expanded according to {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.5.3 section-3.8.5.3].

* until: The value type '''MUST''' be the same as the [[#Start date]] property. If [[#Start date]] was specified as date-time in local time without Timezone information the until date-time '''MUST''' be specified as local-time. If [[#Start date]] was specified as date-time in UTC or local time with Timezone information then the until date-time '''MUST''' be specified as UTC date-time.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.5.3 section-3.8.5.3]

====== Recurrence date ======

  property-rdate = element rdate {
    element parameters {
        [[#xCal Timezone Identifier|xcal-tzid]] ?
    } ?,
    [[#xCal Date-Time|xcal-date-or-date-time]] +
  }

''A list of dates which should be added to the recurrences. An alternative format to the [[#Recurrence rule]]''

While {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.5.2 section-3.8.5.2] permits the usage of a "PERIOD" type for this property to change the duration of a specific recurrence, this '''MUST NOT''' be used. The different duration '''SHOULD''' be indicated by specifying a [[#Recurrence exception]] instead.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.5.2 section-3.8.5.2]

====== Exception date ======

  property-exdate = element exdate {
    element parameters {
      [[#xCal Timezone Identifier| xcal-tzid]] ?
    }?,
    [[#xCal Date-Time|xcal-date-or-date-time]] +
  }

''A list of dates to be excluded from the calculated recurrence set.''

Recurrences with a start date matching an exception date '''MUST''' be excluded from the recurrence set.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.5.1 section-3.8.5.1]

====== Recurrence ID ======

  property-recurrence-id = element recurrence-id {
    element parameters {
      [[#xCal Timezone Identifier| xcal-tzid]] ?,
      element range { element text { "THISANDFUTURE" } }?
    }?,
    [[#xCal Date-Time|xcal-date-or-date-time]]
  }

''A date-time value, matching the [[#Start date]] of one specific recurrence to identify it.''

The value type '''MUST''' be the same as the [[#Start date]] property. If [[#Start date]] was specified as date-time in local time without Timezone information the until date-time '''MUST''' be specified as local-time.
If [[#Start date]] was specified as date-time in UTC or local time with Timezone information then the until date-time '''MUST''' be specified as UTC date-time.

This property '''MUST NOT''' be specified on the base object, but only on a [[#Recurrence exception]].

If this property does not match any recurrence in the defined recurrence set, the whole [[#Recurrence exception]] '''MUST''' be ignored.

* "range": If the range parameter is specified, not only the matched recurrence is subject to the changes in the [[#Recurrence exception]] but also all future recurrences.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.4.4 section-3.8.4.4]

===== Summary =====

  property-summary = element summary {
    element text { [[#String]] }
  }

''A brief description of the object.''

This property '''MAY''' be interpreted as "title" or "display name" of the object.
This property '''SHOULD''' be prominently visible to the user in a client implementation as it is one of the primary means for identifaction of the object.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.1.12 section-3.8.1.12]

===== Description =====

  property-description = element description {
    element text { [[#String]] }
  }

''A more complete description of the incidence.''

This property '''MAY''' be interpreted as "body" or "content" of the object.
This property serves the purpose of attaching more information to the object.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.1.5 section-3.8.1.5]

===== Priority =====

  property-priority = element priority {
    element integer { [[#Integer|xsd:integer]] { minInclusive = "0" maxInclusive = "9" } }
  }

''Priority of the object.''

The range '''MUST''' be in the range 0 to 9. 
* 0 specifies an undefined priority. 
* 1 specifies the highest priority. 
* 9 specifies the lowest priority,

This property gives the user the possibilty to prioritize various objects.
A client implementation '''SHOULD''' give the user the possibilty to sort objects according to priority.

A client implementation '''MAY''' use only a subset of priorities but it '''MUST''' understand all priority values. If a client implementation uses a range with a lower granularity it '''SHOULD''' preserve the original value if it is not modified. It '''SHOULD''' also define a mapping which preserves the meaning of the value.

{{note|Example|If only 0(high), 5(normal), and 9(low) would be used the client implementation should define a mapping such as 0-2 => high, 3-6 => normal, 7-9 => low. A mapping of 0 => high, 1 => normal, 2-9 => low would not preserve the meaning because 1 is considered a "high" priority.}}

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.1.9 section-3.8.1.9]

{{note|Obsoletion of KEP 8|This obsoletes [[KEP:8]]<ref name="kep8">[[KEP:8]] Priority for events, matching iCalendar priority range</ref> as priority ranges now are those of iCalendar.}}

===== Status =====

  property-status = element status {
    element text { [[#String]] }
  }

''Status of the incidence.''

For a [[#Todo]] it '''MUST''' be one of "NEEDS-ACTION", "COMPLETED", "IN-PROCESS", "CANCELLED".

For an [[#Event]] it '''MUST''' be one of "TENTATIVE", "CONFIRMED", "CANCELLED".

For a [[#Journal]] it '''MUST''' be one of "DRAFT", "FINAL", "CANCELLED".

The status of an incidence '''SHOULD''' be reflected in the visualization of an incidence.

{{note|Example|A "COMPLETED" task probably doesn't need as much attention as one of the status "NEEDS-ACTION", a client implementation can use that information to help prioritizing tasks.}}

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.1.11 section-3.8.1.11]

===== Percent complete =====

  property-percent = element percent-complete {
    element integer { [[#Integer|xsd:integer]] { minInclusive = "0" maxInclusive = "100" } }
  }

''The work progress of a task, in percent.''

The range '''MUST''' be from 0 to 100, with 0 indicating the task has not been started and 100 indicating the task has been completed.

The "percent-complete" property ''MAY''' have the value 100 without the [[#Status]] property being set on "COMPLETED". This indicates that all necessary work has been done, but the todo is still not entierly completed.

{{note|Example|For instance all the work on a todo could be done already, but the user is still waiting for a confirmation or alike until he marks the todo as completed.}}

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.1.8 section-3.8.1.8]

===== Location =====

  property-location = element location {
    element text { [[#String]] }
  }

''A textual description of the intended location of the incidence.''

This '''MAY''' be an address or any other textual description of the location.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.1.7 section-3.8.1.7]

===== Organizer =====

  property-organizer = element organizer {
    element parameters {
      element cn { element text { [[#String]] } } ?,
      element dir { element uri { [[#UID|uri-uid]] } } ?
    } ?,
    element cal-address { [[#Mailto URI]] }
  }

''The organizer of the incidence.''

The cal-address '''MUST''' be a valid [[#Mailto URI]].
A contact '''MAY''' be referenced using the [[#UID|uri-uid]].

* The cn parameter '''SHALL''' represent the display name of the organizer.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.4.3 section-3.8.4.3]

===== Attendee =====

  property-attendee = element attendee {
    element parameters {
      element cn { element text { [[#String]] } } ?,
      element rsvp { element boolean { xsd:boolean } } ?,
      element partstat { element text {
        "NEEDS-ACTION" |
        "ACCEPTED" |
        "DECLINED" |
        "TENTATIVE" |
        "DELEGATED"
      } } ?,
      element role { element text {
        "CHAIR" |
        "REQ-PARTICIPANT" |
        "OPT-PARTICIPANT" |
        "NON-PARTICIPANT"
      } } ?,
      element dir { element uri { [[#UID|uri-uid]] } } ?,
      element delegated-to { element cal-address { [[Mailto URI]] } + } ?,
      element delegated-from { element cal-address { [[Mailto URI]] } + } ?,
      element cutype { element text {
        "INDIVIDUAL" |
        "GROUP" |
        "RESOURCE" |
        "UNKNOWN" |
        "ROOM"
      } } ?,
    }?,
    element cal-address { [[Mailto URI]] }
  }

''An attendee of an event.''

The cal-address '''MUST''' be a valid [[Mailto URI]].
A contact '''MAY''' be referenced using the [[#UID|uri-uid]].

* "cn": The display name of the contact.
* "rsvp": Used by the [[#Organizer]] to request a participation status reply from an attendee of a group-scheduled event or to-do.  This parameter '''SHALL''' default to "FALSE" if not specified.
* "partstat": The participation status of the attendee. A client implementation '''MAY''' decide to automatically send an email to the [[#Organizer]] of the event if the "rsvp" parameter is set. This parameter '''SHALL''' default to "NEEDS-ACTION" if not specified.
:* "NEEDS-ACTION": Event needs action.
:* "ACCEPTED": Event accepted.
:* "DECLINED": Event declined.
:* "TENTATIVE":  Event tentatively accepted.
:* "DELEGATED": Event delegated.
* "role": The indended role the attendee will have. This parameter '''SHALL''' default to "REQ-PARTICIPANT" if not specified.
:* "CHAIR": Indicates chair of the calendar entity.
:* "REQ-PARTICIPANT": Indicates a participant whose participation is required.
:* "OPT-PARTICIPANT": Indicates a participant whose participation is optional.
:* "NON-PARTICIPANT": Indicates a participant who is copied for information purposes only.
* "dir": A uri pointing to a directory entry of the attendee.
* "delegated-to": Specifies the address of a calendar user to whom the attendee delegated participation.
* "delegated-from": Specifies the address of a calendar user that has delegated his participation to this attendee.
* "cutype": The type of attendee. This parameter '''SHALL''' default to "INDIVIDUAL".
:* "INDIVIDUAL": Marks the attendee as an indiviual.
:* "GROUP": Marks the attendee as a group of individuals. Useful to add e.g. a mailinglist as attendee.
:* "RESOURCE": Marks the attendee as a physical resource. Used for Resource Management.
:* "UNKNOWN": Should not be used.  Undefined semantics.
:* "ROOM": Should not be used. Undefined semantics.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.4.1 section-3.8.4.1]

{{note|cal-address/dir|While a urn uri would also be valid in cal-address according to iCal, dir seems to be more according to the intentions of iCal, as a uri for a vcard is not strictly a "contact address"}}
{{note|cal-address|The cal-address would allow for any uri, it was restricted to keep clients from having to handle arbitrary contact mediums.}}
{{note|cutype|"UNKNOWN" and "ROOM" were added for RFC compatibility reasons.}}

===== Attachment =====

  property-attach = element attach {
    element parameters {
           element fmttype { element text { [[#String]] } },
           element x-label { element text { [[#String]] } } ?,
           element encoding { element text { "BASE64" } } ?
    },
    element uri { [[#URI|xsd:anyURI]] } |
    element binary { [[#String|xsd:string]] }
  }

''A file attachment.''

The attachment '''MUST''' either be referenced using the uri element or embedded using the binary element.

* "fmttype": '''MUST''' be set to the mimetype of the file.
* "x-label": '''MAY''' be used to add a user visible label for the attachment (such as the filename).
* "encoding": '''MUST''' be set to "BASE64" for inline encoding. This parameter '''MUST''' be set if inline storage using the binary element is used.

The binary content '''MUST''' be "Base 64"-encoded according to {{rfc|4648}}<ref name=rfc4648>{{rfc|4648|The Base16, Base32, and Base64 Data Encodings}}</ref>[https://tools.ietf.org/html/rfc4648#section-4 section-4]

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.1.1 section-3.8.1.1]

{{note|Attachments in separate Mimeparts|Attachments '''SHOULD''' be attached using a seperate Mime-Part. If this technique is used the Attachment '''MUST''' be referenced using the Content-Id(cid:) of the Mimepart in the uri element.}}
{{note|x-label|This property should be replaced with something standard compliant or added to the official standard.}}

==== Alarm ====

  property-trigger = element trigger {
    (
      element parameters {
        element related { element text { "START" | "END" } } ?
      }?,
      element duration { [[#Duration]] }
    ) | (
      [[#xCal Date-Time|xcal-date-time]]
    )
  }

''Specifies the trigger either on a specific date or with a combination of a duration relative to the [[#Start date]] or the [[#End date]] of the incidence.''

* "related": Indicates if the trigger should be a duration of "duration" before the [[#Start date]] or the [[#End date]].  If not specified this parameter '''SHALL''' default to "START".

The duration '''SHALL''' denote the duration before either the [[#Start date]] or the [[#End date]] occurs, depending on the "related" parameter.

For [[#Todo]] components, instead of the [[#End date]] either the [[#Due date]] or the [[#Start date]] + [[#Duration]] '''SHALL''' be used.

If a date-time value is used it '''MUST''' be in UTC.

  type-emailprop = element properties {
    element action { text { "EMAIL" } },
    element summary { [[#Summary]] },
    element description { [[#Description]] },
    element attendee { element cal-address { [[#Mailto URI]] } } +,
    property-trigger,
    (
      element duration { [[#Duration]] },
      element repeat { element integer { [[#Integer|xsd:integer]] } }
    ) ?
  }

''An email alarm, which sends an email to each attendee on trigger.''

Properties:
* "summary": The subject line of the email
* "description": The body of the email.
* "attendee": A receipent of the email alarm.
* "duration": Interval for additional repetitions.
* "repeat": Number of repetitions additionally to the trigger. (0 repetitions results in 1 execution of the alarm)

  type-audioprop = element properties {
    element action { text { "AUDIO" } },
    element attach { [[#Attachment]] } ?
    property-trigger,
    (
      element duration { [[#Duration]] },
      element repeat { element integer { [[#Integer|xsd:integer]] } }
    ) ?
  }

''An audio alarm, which plays a sound on trigger.''

* The attach property '''MUST''' point to an audio resource, which is rendered when the alarm is triggered.

  type-dispprop = element properties {
    element action { text { "DISPLAY" } },
    element description { [[#Description]] },
    property-trigger,
    (
      element duration { [[#Duration]] },
      element repeat { element integer { [[#Integer|xsd:integer]] } }
    ) ?
  }

''A display alarm which displays a message to the user on trigger.''

  component-valarm = element valarm {
    type-audioprop | type-dispprop | type-emailprop
  }

''An alarm which can be added to todos or events''

Interpretation of all values '''MUST''' be according to {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.6.6 section-3.6.6].

An alarm can trigger repeatedly by setting "duration", which '''SHALL''' indicate the break between alarms and "repeat", which '''SHALL''' indicate the number of repetitions.

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.6.6 section-3.6.6]

{{note|Unsupported KDE feature: X-KDE-KCALCORE-ENABLED|KAlarm allows to disable alarms without deleting it. This is not supported by xcal.}}

==== Todo ====

  todo = element vtodo {
    element properties {
      element uid { [[#UID|text-uid]] },
      element created { [[#Creation date]] },
      element dtstamp { [[#Last modification date]] },
      element sequence { [[#Sequence]] }, ?
      element class { [[#Classification]] } ?,
      element categories { [[#Categories|property-categories]] } ?,
      element related-to { [[#Related-to]] } *,
      element dtstart { [[#Start date]] } ?,
      element due { [[#Due date]] } ?,
      element rrule { [[#Recurrence rule]] } ?,
      element rdate { [[#Recurrence date]] } ?,
      element exdate { [[#Exception date]] } ?,
      element recurrence-id { [[#Recurrence ID]] } ?,
      element summary { [[#Summary]] } ?,
      element description { [[#Description]] } ?,
      element priority { [[#Priority]] } ?,
      element status { [[#Status]] } ?,
      element percent-complete { [[#Percent complete]] } ?,
      element location { [[#Location]] } ?,
      element organizer { [[#Organizer]] } ?
      element attendee { [[#Attendee]] } *,
      element attach { [[#Attachment]] } *,
      element x-custom { [[#Kolab Custom Property]] } *
    },
    element components {
      element valarm { [[#Alarm|alarm]] } +
    }?
  }

''An object representing a task/todo.''

* Content-Type: application/calendar+xml
* X-Kolab-Type: application/x-vnd.kolab.task

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.6.2 section-3.6.2]

{{note|transp|transp does not apply to todo, and show-time-as from the old format spec is not supported. show-time-as is a further specification, which allows to specify how exactly one is not available (out of office, busy but in the office, meeting, ...). Something for a future version maybe.}}

==== Event ====

  event = element vevent {
    element properties {
      element uid { [[#UID|text-uid]] },
      element created { [[#Creation Date]] },
      element dtstamp { [[#Last modification date]] },
      element sequence { [[#Sequence]] }, ?
      element class { [[#Classification]] } ?,
      element categories { [[#Categories|property-categories]] } ?,
      element dtstart { [[#Start date]] },
      element dtend { [[#End date]] } ? |
      element duration { [[#Incidence Duration]] } ?,
      element transp { [[#Transparency]] } ?,
      element rrule { [[#Recurrence rule]] } ?,
      element rdate { [[#Recurrence date]] } ?,
      element exdate { [[#Exception date]] } ?,
      element recurrence-id { [[#Recurrence ID]] } ?,
      element summary { [[#Summary]] } ?,
      element description { [[#Description]] } ?,
      element priority { [[#Priority]] } ?,
      element status { [[#Status]] } ?,
      element location { [[#Location]] } ?,
      element organizer { [[#Organizer]] } ?
      element attendee { [[#Attendee]] } *,
      element attach { [[#Attachment]] } *,
      element x-custom { [[#Kolab Custom Property]] } *
    },
    element components {
      element valarm { [[#Alarm|alarm]] } +
    }?
  }

''An object representing an event.''

* Content-Type: application/calendar+xml
* X-Kolab-Type: application/x-vnd.kolab.event

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.6.1 section-3.6.1]

{{note|Obsoletion of KEP 3|This obsoletes [[KEP:3]]<ref name="kep3">[[KEP:3]] Introduction of subevent sub-tag for exclusion from recurrence</ref> as recurrences are now handled as set forth in the KEP by handling them as specified in iCalendar.}}

==== Journal ====

  journal = element vjournal {
    element properties {
      element uid { [[#UID|text-uid]] },
      element created { [[#Creation Date]] },
      element dtstamp { [[#Last modification date]] },
      element sequence { [[#Sequence]] }, ?
      element class { [[#Classification]] } ?,
      element categories { [[#Categories]] } ?,
      element dtstart { [[#Start date]] } ?,
      element summary { [[#Summary]] } ?,
      element description { [[#Description]] } ?,
      element status { [[#Status]] } ?,
      element attendee { [[#Attendee]] } *,
      element attach { [[#Attachment]] } *,
      element x-custom { [[#Kolab Custom Property]] } *
    }
  }

An object representing an journal entry. Journal entries '''SHALL''', as opposed to notes, be related to a calendar date.

* Content-Type: application/calendar+xml
* X-Kolab-Type: application/x-vnd.kolab.journal

Implements:
* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.6.3 section-3.6.3]

=== xCard based objects ===

All xCard based objects '''MUST''' fully comply to {{rfc|6351}}<ref name="rfc6351" />.

Each Kolab XML Object '''MUST''' contain exactly one contact/distribution list object stored according to {{rfc|6351}}<ref name="rfc6351" />.

==== Properties ====

===== Kind =====

  property-kind = element kind {
    element text { "individual" | "group" }
  }

''Specifies the kind of xCard object.''

This property '''MUST''' be set to "individual" for [[#Contact]] objects.

This property '''MUST''' be set to "group" for [[#Distribution List]] objects.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.1.4 section-6.1.4]

===== Name =====

  property-fn = element fn {
    element text { [[#String]] }
  }

''A formatted text corresponding to the name of the contact/distribution list.''

This property '''SHOULD''' be the primary identifier for a user to recognize the contact.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.2.1 section-6.2.1]

===== Name Components =====

  property-n = element n {
    element surname { [[#String]] }*,
    element given { [[#String]] }*,
    element additional { [[#String]] }*,
    element prefix { [[#String]] }*,
    element suffix { [[#String]] }*
  }

''Specifies the indvidual components the name of the contact consists of.''

Components:
* "surname": A surname (familyname) of the contact.
* "given": A given name of the contact.
* "additional": An additional name.
* "prefix": A honorific prefix.
* "suffix": A honorific suffix.

Client implementations '''SHOULD''' be able to handle multiple values of each component.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.2.2 section-6.2.2]

===== Note =====

  property-note = element note {
    element text { [[#String]] }
  }

''To specify supplemental information or a comment that is associated with the contact.''

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.7.2 section-6.7.2]

===== Freebusy URL =====

  property-fburl = element fburl {
    element uri { [[#URI|xsd:anyURI]] }
  }

''Specifies the URI for the busy time associated with the contact.''

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.9.1 section-6.9.1]

{{note|Needs clarification: Type| do we need to indicate the type where this points?}}
{{note|Needs clarification: cardinality| do we need multiple fb urls?}}

===== Title =====

  property-title = element title {
    element text { [[#String]] }
  }

''Specifies a position or profession of the contact.''

In contrast to [[#Role]], this property denotes a general profession/occupation of the contact, and is not bound to a specifc organization.

Examples:
  * "Computer Scientist"

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.6.1 section-6.6.1]

{{note|Possible error in vCard RFC|The reference in the vCard RFC to CCITT.X520.1988:Title is likely wrong and should be CCITT.X520.1988:Business Category. This would align with the example in the vCard RFC and is how we're using it.}}

===== Affiliation =====

Affiliation specific elements are grouped by a "group" element.
The "group" element is the xCard equivalent to the "group construct" as specified in {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-3.3 section-3.3] and is specified in {{rfc|6351}} [http://tools.ietf.org/html/rfc6351#section-5 section-5].

A contact '''MAY''' be associated with multiple organizations by using multiple affiliation groups.

{{note|Implementation note|This corresponds to kaddressbooks business tab}}

====== Organization ======

  property-org = element org {
    element text { [[#String]] } +
  }

''A organization associated with the contact''

A single "org" property '''MUST''' be used for only one organization.

Organizations are of no specific type.

The first text value '''MUST''' denote the organizations name.

Further text values '''MAY''' be appended to denote organizational units the contact is associated with.

{{note|Example|Examples for this property are the name of a company or the name of a book club.}}

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.6.4 section-6.6.4]

{{note|Note: Better modeling of organizations|We could add a link to a organization vcard here. This would also allow to add a address which is associated with the organization etc. It would add complexity to the client though}}

====== Logo ======

  property-logo = element logo {
    element uri { [[#URI inline encoding]] }
  }

''A logo of the organization the contact is affiliated with''

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.6.3 section-6.6.3]

{{note|Implementation note: Roundcube|roundcube does not support this property, but only the photo}}
{{note|Purpose|The purpose of this property was changed so the logo is now associated with the affiliated organization and not the "object the vCard presents" as the RFC puts it, which is how it is also used in Kontact}}

====== Role ======

  property-role = element role {
    element text { [[#String]] }
  }

''Specifies a role/function of the contact within the organization.''

In contrast to [[#Title]], this property denotes a specific role/function within an organization, and not a generic profession/occupation.

Examples:
  * "Systems Architect"
  * "Manager,Distributed Applications"

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.6.2 section-6.6.2]

{{note|Possible error in vCard RFC|The reference in the vCard RFC to CCITT.X520.1988:Business Category is likely wrong and should be CCITT.X520.1988:Title. This would align with the example in the vCard RFC and is how we're using it.}}

===== URL =====

  property-url = element url {
    element parameters { element type { element text { "x-blog" } } } ?,
    element uri { [[#URI|xsd:anyURI]] }
  }

''A generic URL which is related to the contact.''

The the following types '''SHOULD''' be used to indicate the type of the URL.
* "x-blog": Indicates that the URL points to a blog related to the contact.

If no type is specified, the URI '''SHALL''' be interpreted as generic website related to the contact.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.7.8 section-6.7.8]

{{note|RFC conflict|RFC 6351 permits only home, work types although RFC 6350 permits own x-values. An erratum has been submitted and confirmed.}}
{{note|x-blog|This property should be replaced with something standard compliant or added to the official standard.}}

===== Address =====

  property-adr = element adr {
    element parameters {
      element pref { element integer { 1 } } ?,
      element type {
        element text { "work" | "home" } +
      } ?,
      element label { [[#String]] } ?
    } ?,
    element pobox { [[#String]] },
    element ext { [[#String]] },
    element street { [[#String]] },
    element locality { [[#String]] },
    element region { [[#String]] },
    element code { [[#String]] },
    element country { [[#String]] }
  }

''An address of the contact or organization.''

Address components:
* "pobox": The post office box. This component '''SHOULD NOT''' be used as recommended by {{rfc|6350}}[https://tools.ietf.org/html/rfc6350#section-6.3.1 section-6.3.1].
* "ext": The extended address (e.g., apartment or suite number). This component '''SHOULD NOT''' be used as recommended by {{rfc|6350}}[https://tools.ietf.org/html/rfc6350#section-6.3.1 section-6.3.1].
* "street":  The street address.
* "locality": The locality (e.g., city).
* "region": The region (e.g., state or province).
* "code": The postal code.
* "country": The country name. Countries '''SHALL''' be named according to the official short names in english specified in ISO 3166-1 which can be looked up here [http://www.iso.org/iso/list-en1-semic-3.txt]<ref name="iso3166-1">official short names in English [http://www.iso.org/iso/list-en1-semic-3.txt]</ref>.

The following types are defined:
* "work": Indicates that the address is work related.
* "home": Indicates that the address is home address.

{{note|Implementation note: type|"intl", "dom", "postal", and "parcel" have been removed from the types section during the update from RFC2426 to RFC6350 and are therefore no longer supported. This means these values will be lost when saving an address from Kontact.}}

The "pref" parameter '''MAY''' be used to indicate the preferred address. Only one address '''SHOULD''' be marked as preferred address.

The "label" parameter '''MAY''' be used to set a label for the address which client implementations '''SHOULD''' present to the user as primary means for identification of the address.

If used within an [[#Affiliation]] this property '''SHALL''' be used for any related address, such as an office of the organization. The "label" parameter '''MAY''' be used to store a freeform version of such a location description (i.e. office).

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.3.1 section-6.3.1]

===== Nickname =====

  property-nickname = element nickname {
    element text { [[#String]] } *
  }

''A list of nicknames.''

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.2.3 section-6.2.3]

===== Related =====

  property-related = element related {
    element parameters {
      element type {
        element text {
          "spouse" | "child" | "x-manager" | "x-assistant"
        } +
      }?
    }?,
    ( element uri { [[#UID|uri-uid]] } | element text { [[#String]] } )
  }

''Specifies a relation of the contact to another contact.''

Clients SHALL use a [[#UID|uri-uid]] to reference a Contact object when using the uri element.
Clients MUST be able to deal with [[#UID|uri-uid]].

Types:
* "spouse": Specifies that the related contact is the spouse of this contact. This value '''SHOULD''' only occur within the toplevel related property.
* "child": Specifies that the related contact is the child of this contact. This value '''SHOULD''' only occur within the toplevel related property.
* "x-manager": Specifies a manager of the contact within the organization. This value '''SHOULD''' only occur within related properties within an [[#Affiliation]].
* "x-assistant": Specifies an assistant of the contact within the organization. This value '''SHOULD''' only occur within related properties within an [[#Affiliation]].

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.6.6 section-6.6.6]

{{note|Note: manager/assistat|The two x-values should be submitted to the vCard RFC.}}

===== Birthday =====

  property-bday = element bday {
    [[#xCard Date-Time|xcard-date-time]]
  }

''The birthday of the contact.''

The date-time value '''MUST''' be in local time.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.2.5 section-6.2.5]

===== Anniversary =====

  property-anniversary = element anniversary {
    [[#xCard Date-Time|xcard-date-time]]
  }

''The anniversary of the relationship the contact is part of.''

The date-time value '''MUST''' be in local time.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.2.6 section-6.2.6]

===== Photo =====

  property-photo = element photo {
    element uri { [[#URI inline encoding]] }
  }

''An image or photograph representing the contact.''

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.2.4 section-6.2.4]

===== Gender =====

  property-gender = element gender {
    element sex { "" | "M" | "F"}
  }

''Specifies the gender of the contact.''

Values:
* "": Not specified
* "M": Male
* "F": Female

If this property is not specified it '''SHALL''' default to "".

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.2.7 section-6.2.7]

===== Language =====

  property-lang = element lang {
    element language-tag { [[#String]] }
  }

''A language that '''MAY''' be used to contact the contact.''

A language '''MAY''' be defined freely and does not follow a naming-scheme.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.4.4 section-6.4.4]

===== Telephone =====

  property-tel = element tel {
    element parameters {
      element pref { element integer { 1 } } ?,
      element type {
        element text { "work" | "home" | "text" | "voice"
                     | "fax" | "cell" | "video" | "pager"
                     | "textphone" | "x-car" }+
      }?
    }?,
    element text { [[#String]] }
  }

''A telephone number.''

A telephone number '''MAY''' have one or more type defined.

The following types are defined:
* "work": Indicates that the telephone number is work related.
* "home": Indicates that the telephone number is private.
* "text": Indicates that the telephone number supports text messages (SMS).
* "voice": Indicates a voice telephone number.
* "fax": Indicates a fax machine telephone number.
* "cell": Indicates a cellular or mobile telephone number.
* "video": Indicates a video conferencing telephone number.
* "pager": Indicates a paging device telephone number.
* "textphone": Indicates a telecommunication device for people with hearing or speech difficulties.
* "x-car": Indicates the telephone number of a car.

Only the defined types '''MUST''' be used.

If a client implementation uses another undefined type, this type '''SHALL''' be mapped to the most suitable of the defined values.

The "pref" parameter '''MAY''' be used to indicate a preferred telephone number. Multiple numbers '''MAY''' be marked as preferred.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.4.1 section-6.4.1]

{{note|RFC conflict|RFC 6351 permits only work,home,text,voice,fax,cell,video,pager,textphone types although RFC 6350 permits own x-values. An erratum has been submitted and confirmed.}}
{{note|Implementation note: tel uri|The alternative uri value has been removed as Kontact and RC use plain strings so far. The uri value should be added if we want to use tel uris.}}
{{note|Implementation note: KDE compatibility|KAddressbook supports additionally messenger, mailbox, modem, isdn and pcs types. Those were not added because they dont seem useful. Every client implementation has to support all defined values, therefore we MUST only add sensible values. Allowing clients to specify their own types (x-values) would lead implementations having to preserve those, and numbers not being displayed at all. Obviously the current solution leads to the type being changed to one of the defined ones if an unknown type is used.}}
{{note|Implementation note: RC compatibility|RC additionaly specifies callback, company, isdn, radio, telex, tty/tdd, assistant which cannot be mapped with the current set of types.}}

===== IM Address =====

  property-impp = element impp {
    element parameters { element pref { element integer { 1 } } } ?,
    element uri { [[#URI|xsd:anyURI]] }
  }

''A Instant Messenger contact.''

The "pref" parameter '''MAY''' be used to indicate the preferred IM address. Only one IM address '''SHOULD''' be marked as preferred address.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.4.3 section-6.4.3]

{{note|Note: application type|They application should be chosen based on the protocol indicated by the uri.}}

===== EMail =====

  property-email = element email {
    element parameters { element pref { element integer { 1 } } } ?,
    element text { [[#String]] }
  }

''An email address of the contact.''

The text value '''SHOULD''' be interpreted as addr-spec according to {{rfc|5322}}<ref name="rfc5322">{{rfc|5322}} Internet Message Format</ref> [https://tools.ietf.org/html/rfc5322#section-3.4.1].

The "pref" parameter '''MAY''' be used to indicate the preferred email address. Only one email address '''SHOULD''' be marked as preferred address.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.4.2 section-6.4.2]

===== Global Positioning =====

  property-geo = element geo {
    element uri{ [[#Geo URI]] }
  }

''Specifies a global position of the contact.''

The global position '''SHOULD''' be interpreted as a location which is related to the contact, respectively meaningful for the user of the contact object.

{{note|Example|This could be the hometown of the contact or the place the user met the contact.}}

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.5.2 section-6.5.2]

===== Cryptographic Key =====

  property-key = element key {
    element uri { [[#URI inline encoding]] }
  }

''Specifies a public key or authentication certificate associated with the contact. ''

This key ''MAY'' be used to encrypt or sign using OpenPGP or S/MIME. The embedded key '''MUST''' have the type "application/pgp-keys" or "application/pkcs7-mime".

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.8.1 section-6.8.1]

===== Cryptographic Preferences =====

  property-crypto = element x-crypto {
    element allowed { element text { "PGP/INLINE" | "PGP/MIME" | "S/MIME" | "S/MIMEOpaque" }* },
    element signpref { element text { "Never" | "Always" | "IfPossible" | "Ask" } } ?,
    element encryptpref {  element text { "Never" | "Always" | "IfPossible" | "Ask" } } ?
  }

''Specifies crypto related settings.''

* "allowed": Specifies the allowed encryption/signing protocols for incoming content:
:* "PGP/INLINE": Allows inline-PGP for encrypted and signed content.
:* "PGP/MIME": Allows PGP/MIME for encrypted and signed content.
:* "S/MIME": Allows clear signed messages using S/MIME.
:* "S/MIMEOpaque": Allows opaque signed messages using S/MIME.
* "signpref": This preference '''SHOULD''' be considered when sending content to the contact. If not specified this preference '''SHALL''' default to "Ask"
:* "Never": Never sign something before sending.
:* "Always": Alway sign, abort if signing is not possible.
:* "IfPossible": Sign if possible, otherwise just send unsigned.
:* "Ask": Always ask the user what to do.
* "encryptpref": This preference '''SHOULD''' be considered when sending content to the contact. If not specified this preference '''SHALL''' default to "Ask"
:* "Never": Never encrypt something before sending.
:* "Always": Alway encrypt, abort if encryption is not possible.
:* "IfPossible": Encrypt if possible, otherwise just send unencrypted.
:* "Ask": Always ask the user what to do.

These properties '''MAY''' be considered in email communication with the client.

Uses:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.8.1 section-6.8.1]
* {{rfc|4880}}<ref name=rfc4880>{{rfc|4880}} OpenPGP Message Format</ref> [https://tools.ietf.org/html/rfc4880]
* {{rfc|5751}}<ref name=rfc5751>{{rfc|5751}} Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.2 Message Specification</ref> [https://tools.ietf.org/html/rfc5751]

{{note|Opaque signing|Opaque signing refers to the technique of embedding the text into the base64 encoded CMS (PKCS #7 based Cryptographic Message Syntax) object (content type: application/x-pkcs7-mime) of the signature, so it can only be read if the client supports S/MIME. Clear signing transmits the clear text and only appends the signature (content type: application/x-pkcs7-signature), which allows clients without S/MIME support to read the message.}}
{{note|Needs clarification: Key storage|Im not sure yet how the key should be stored. Im also dont think the application/pkcs7-mime mimetype is correct for the key itself.}}
{{note|Needs clarification: allowed|Is this correct that it is only for incoming content? (the allowed element is derived from the KAddressbook Crypto settings page)}}
{{note|x-crypto|This property is missing in the xCard standard and should be added to it (probably as crypto-pref).}}
{{note|identities|Ideally crypto settings would be per identity and not per contact.}}

===== Member =====

  property-member = element member {
    element uri { [[#Contact URI]] }
  }

''A member of the distribution list.''

A member '''MUST''' contain a valid [[#Contact URI]].

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.6.5 section-6.6.5]

==== Contact ====

  contact = element vcard {
    element uid { [[#UID|uri-uid]] },
    element x-kolab-version { [[#Kolab XML Version]] },
    element prodid { [[#Product ID]] },
    element rev { [[#Last modified date]] },
    element categories { [[#Categories]] } ?,
    element kind { [[#Kind|"individual"]] },
    element fn { [[#Name]] },
    element n { [[#Name Components]] } ?,
    element note { [[#Note]] } ?,
    element fburl { [[#Freebusy URL]] } ?,
    element title { [[#Title]] } *,
    element group {
      attribute name { [[#Affiliation|"Affiliation"]] },
      element org { [[#Organization]] },
      element logo { [[#Logo]] } ?,
      element role { [[#Role]] } *,
      element related { [[#Related]] } *,
      element adr { [[#Address]] } *
    } *,
    element url { [[#URL]] } *,
    element adr { [[#Address]] } *,
    element nickname { [[#Nickname]] },
    element related { [[#Related]] } *,
    element bday { [[#Birthday]] } ?,
    element anniversary { [[#Anniversary]] } ?,
    element photo { [[#Photo]] } ?,
    element gender { [[#Gender]] } ?,
    element lang { [[#Language]] } *,
    element tel { [[#Telephone]] } *,
    element impp { [[#IM Address]] } *,
    element email { [[#EMail]] } *,
    element geo { [[#Global Positioning]] } *,
    element key { [[#Cryptographic Key]] } *,
    element x-crypto { [[#Cryptographic Preferences]] } ?,
    element x-custom { [[#Kolab Custom Property]] } *
  }

''An address book entry for a contact.''

* Content-Type: application/vcard+xml
* X-Kolab-Type: application/x-vnd.kolab.contact

If the vcard:kind element is absent, it '''MUST''' default to "individual".

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350]

{{note|Obsoletion of KEP 13|This obsoletes draft [[KEP:13]]<ref name="kep13">[[KEP:13]] Update contact object (Draft)</ref> as this update will fully replace everything that KEP would have addressed.}}
{{note|Identities| Contacts currently lack the notion of different identities of the same person, respectively don't support a Person/Identities modeling.}}

==== Distribution List ====

  distlist = element vcard {
    element uid { [[#UID|text-uid]] },
    element x-kolab-version { [[#Kolab XML Version]] },
    element prodid { [[#Product ID]] },
    element rev { [[#Last modification date]] },
    element categories { [[#Categories]] } ?,
    element kind { [[#Kind|"group"]] },
    element fn { [[#Name]] },
    element member { [[#Member]] } *,
    element x-custom { [[#Kolab Custom Property]] } *
  }

''A distribution list mostly used for emailing.''

* Content-Type: application/vcard+xml
* X-Kolab-Type: application/x-vnd.kolab.distribution-list

The vcard:kind element '''MUST''' have the value "group".

=== Note ===

  note = element note {
    attribute version { [[#Kolab XML Version]] },
    element uid { [[#UID|value-uid]] },
    element prodid { [[#Product ID|value-productid]] },
    element creation-date { [[#Creation date|value-creation-date]] },
    element last-modification-date { [[#Last modification date|value-lastmodified-date]] },
    element categories { [[#Categories|category-hierarchy]] } *,
    element classification { [[#Classification|value-classification]] } ?,
    element attachment { [[#Attachment]] } *,
    element summary { [[#String]] } ?,
    element description { [[#String]] } ?,
    element x-custom { [[#Kolab Custom Property]]} *
  }

''A generic note, not necessarily associated with a specific date.''

* Content-Type: application/vnd.kolab+xml
* X-Kolab-Type: application/x-vnd.kolab.note

{{note|structure: attachment|Points to an xCal property? Maybe move the attachment to the generic section.}}

==== Properties ====

=== Configuration ===

  configuration = element configuration {
    attribute version { [[#Kolab XML Version]] },
    element uid { [[#UID|value-uid]] },
    element prodid { [[#Product ID]] },
    element creation-date { [[#Creation date]] },
    element last-modification-date { [[#Last modification date]] },
    element type { [[#String]] },
    configurationtype-fields
  }

''A Kolab configuration object.''

* Content-Type: application/vnd.kolab+xml
* X-Kolab-Type: application/x-vnd.kolab.configuration.TYPE

The TYPE of the X-Kolab-Type '''MUST''' correspond to the "type" element.

The individual configurationtype-fields '''SHALL''' be defined individual KEP proposals. Depending on the "type" value the corresponding configurationtype-fields '''SHALL''' be used.

Implements:
* [[KEP:9]]<ref name="kep9">[[KEP:9]] Storage of configuration and application control information</ref>

{{note|Partial obsoletion of KEP 9|This obsoletes the "Kolab XML object type: 'configuration'" section of [[KEP:9]]<ref name="kep9">[[KEP:9]] Storage of configuration and application control information</ref> but models the issue in an equivalent way. The entire rationale of [[KEP:9]] as well as the Client behaviour guidelines still apply.}}

== Value Types ==

=== Date-Time ===

Following the provisions set forth in {{rfc|6321}} [https://tools.ietf.org/html/rfc6321#section-3.6.5 section 3.6.5], date-time values '''MUST''' be specified as unspecified local time (floating time), UTC, or local time in a specific time zone.

VTIMEZONE fields '''MUST NOT''' be used in Kolab Format 3.0.

UTC-offset times '''MUST NOT''' be used.

A time value '''MUST''' only specify the second 60 when specifying a positive leap second. Implementations that do not support leap seconds '''SHOULD''' interpret the second 60 as equivalent to the second 59.

{{note|Obsoletion of KEP 2|This obsoletes the semantics set forth in [[KEP:2]]<ref name="kep2">[[KEP:2]] Modification of datetime: store local time, add tz attribute</ref> but models the issue in the same way. The entire rationale of [[KEP:2]] why this is the best way to model the problem applies.}}

==== Timezone Identifier ====

For the Kolab Format, the name of that time zone is a string, which '''MUST''' be a geographical time zone identifier in the uniform naming convention designed by Paul Eggert, specifying time zones from the Olson database, a.k.a. tz database, a.k.a. zoneinfo database <ref>[[wikipedia:Zoneinfo | Wikipedia: Zoneinfo]]</ref>.

A Timezone identifier '''MUST NOT''' be specified for UTC date-times.

Clients '''MUST''' preserve user preference and selection in the "tz" attribute to the maximum extent possible.

Clients '''SHOULD''' check if a new update of the Olson database or the authoritative database used by the system is available and get that update at least once every three months, '''OR''' suggest update policies for their respective operating systems that ensure the time zone data database gets updated regularly. As far as is currently known, all commonly used and supported GNU/Linux distributions do this already.

When creating a new object with time zone sensitive fields, clients '''SHOULD''' default to the local time zone of the user, but '''SHOULD''' allow the user to select the time zone for storage.

When modifying existing objects, clients '''MUST''' use the value of the 'tz' attribute of the respective fields to set the default/preselected value for the editing of the fields, where applicable. For instance the 'start-date' and 'end-date' time zone defaults if presented to the user by the client '''MUST''' match those stored in the 'tz' attribute. The time zone stored in the 'tz' attribute '''SHOULD''' only be changed based upon user interaction.

===== tzid mapping table =====

There should be mapping between time zone identifiers from and to the Olson database locations for systems not based on the Olson time zone identifiers, i.e. Microsoft Windows. In order to achieve that, Kolab Systems will work with the various client implementers to provide a canonical mapping table that all clients without Olson database can use for such mapping on their systems against the Olson database locations. This tzid mapping table will be provided publicly under a Free Software license.
Format and usage of that mapping table shall be defined in another KEP. This mapping '''MUST''' be performed on writing that only defined Timezone Identifiers are written to the Kolab XML Object.

===== xCal Timezone Identifier =====

  xcal-tzid = element tzid {
    element text { [[#String]] }
  }

xCal based objects '''MUST''' prefix the timezone identifier with "/kolab.org/".

Implements:
* {{rfc|5545}}<ref name="rfc5545" />[https://tools.ietf.org/html/rfc5545#section-3.8.3.1 section-3.8.3.1]

===== xCal Date-Time =====

  xcal-date-time = date-time {
    xsd:string { pattern = "\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\dZ?" }
  }

  xcal-date = date {
    xsd:string { pattern = "\d\d\d\d-\d\d-\d\d" }
  }

  xcal-date-or-date-time = ( xcal-date | xcal-date-time )

The date and time pattern '''MUST''' be in the format

  "yyyy-MM-dd:hh:mm:ss"

To indicate that a date-time is in UTC a 'Z' '''MUST''' be appended.

Implements:
* {{rfc|6321}} [https://tools.ietf.org/html/rfc6321#section-3.6.4 section 3.6.4]
* {{rfc|6321}} [https://tools.ietf.org/html/rfc6321#section-3.6.5 section 3.6.5]

==== xCard Date-Time ====

  xcard-date-time = date-time {
    xsd:string { pattern = "\d\d\d\d\d\d\d\dT\d\d\d\d\d\dZ?" }
  }

  xcard-date = date {
    xsd:string { pattern = "\d\d\d\d\d\d\d\d" }
  }

  xcard-date-or-date-time = ( xcard-date | xcard-date-time )

The date and time pattern '''MUST''' be in the format

  "yyyyMMddThhmmss"

The date-time value '''MUST''' be a local time as specified in {{rfc|6350}}<ref name="rfc6350" />.
Note that while {{rfc|6350}}<ref name="rfc6350" /> allows the usage of UTC-offset times, this '''MUST NOT''' be used.

To indicate that a date-time is in UTC a 'Z' '''MUST''' be appended.

Implements:
* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-4.3 section 4.3]

==== Examples ====

* Floating Time according to {{rfc|6321}}: <date-time>2011-05-17T13:00:00</date-time>
* UTC according to {{rfc|6321}}: <date-time>2011-05-17T13:00:00Z</date-time>
* Local time in timezone according to {{rfc|6321}}:

    <parameters>
        <tzid><text>/kolab.org/Europe/Zurich</text></tzid>
    </parameters>
    <date-time>2011-05-17T13:00:00</date-time>

* Floating Time according to {{rfc|6351}}: <anniversary><date-time>20090808T143000</date-time></anniversary>

=== Color ===

The value '''SHALL''' be a sRGB[https://secure.wikimedia.org/wikipedia/en/wiki/SRGB|sRGB]<ref name="srgb">[https://secure.wikimedia.org/wikipedia/en/wiki/SRGB] sRGB </ref> color value expressed in a 6-digit hexadecimal web color[https://secure.wikimedia.org/wikipedia/en/wiki/Web_colors]<ref name="srgb">[https://secure.wikimedia.org/wikipedia/en/wiki/Web_colors] Web_colors </ref> with the magic value of 'XXXXXX' referring to an explicit 'No Color' selection.

=== String ===

Strings '''MUST''' be represented as defined by xsd:string in [http://www.w3.org/TR/xmlschema-2/#string].

=== Integer ===

An integer as defined by xsd:positiveInteger, xsd:negativeInteger and xsd:integer in [http://www.w3.org/TR/xmlschema-2/#integer].

=== Duration ===

  pattern-duration = xsd:string {
    pattern = "(+|-)?P(\d+W)|(\d+D)?"
            ~ "(T(\d+H(\d+M)?(\d+S)?)|"
            ~   "(\d+M(\d+S)?)|"
            ~   "(\d+S))?"
  }

A duration according to {{rfc|6321}} [https://tools.ietf.org/html/rfc6321#section-3.6.6 section 3.6.6].

Implements:
* {{rfc|6321}} [https://tools.ietf.org/html/rfc6321#section-3.6.6 section 3.6.6]

=== URI ===

A URI '''MUST''' be represented as defined by xsd:anyURI in [http://www.w3.org/TR/xmlschema-2/#anyURI].

==== URI inline encoding ====

The encoding '''MUST''' be "Base 64" according to {{rfc|4648}}<ref name=rfc4648>{{rfc|4648|The Base16, Base32, and Base64 Data Encodings}}</ref>[https://tools.ietf.org/html/rfc4648#section-4 section-4]

The uri scheme '''MUST''' be according to {{rfc|2397}}<ref name="rfc2397">{{rfc|2397}} The "data" URL scheme"</ref>.[https://tools.ietf.org/html/rfc2397]

===== Example =====

  data:image/jpeg;base64,MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhv
  AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm
  ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0
  <...remainder of base64-encoded data...>

  data:application/pgp-keys;base64,MIICajCCAdOgAwIBAgICBE
  UwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05l
  <... remainder of base64-encoded data ...>

==== Mailto URI ====

A Mailto URI '''MUST''' conform to {{rfc|6068}}<ref name="rfc6068">{{rfc|6068}} The 'mailto' URI Scheme</ref>.

The name of the contact '''MAY''' be embedded in the email address as specified in {{rfc|822}}<ref name="rfc822">{{rfc|822}} Standard for ARPA Internet Text Messages</ref> [https://tools.ietf.org/html/rfc822#section-6.1 section-6.1].
This technique '''SHALL''' only be used if no other means to indicate the name are available.
In case the name is included, URL-reserved characters '''MUST''' be encoded.

Example:

  mailto:John%20Doe%3cjdoe@example.com%3e

== Contact URI ==

  value-uri = xsd:AnyURI

''Any URI which is somehow relevant to identify/contact a Contact.''

Clients SHALL either use a [[#UID|uri-uid]] to reference a Contact object or a [[#Mailto URI]] to specify a single email address.
Clients MUST be able to deal with both [[#UID|uri-uid]] and [[#Mailto URI]].

==== Geo URI ====

A geographic location identifier '''MUST''' conform to {{rfc|5870}}<ref name="rfc5870">{{rfc|5870}} A Uniform Resource Identifier for Geographic Locations ('geo' URI)</ref>.

== Versioning ==

=== Version number ===

A Version number '''MUST''' be a string according to [[KEP:5]]<ref name="kep5">[[KEP:5]] Server Product Versioning</ref>

The version number '''SHALL''' reflect the Kolab XML Format definition version.
An implementation '''SHOULD NOT''' write to a file with a higher version number, because that will potentially lead to data loss.

Due to the different formats of the Kolab XML Objects the version number is stored in different places:
* Objects according to {{rfc|5545}} <ref name="rfc5545">{{rfc|5545|title=XML Representation of iCal (xCal)}}</ref> such as Event/Todo contain the version number in the x-kolab-version element which '''MUST''' be contained in the vcalendar properties sequence.
* Objects according to {{rfc|6350}} <ref name="rfc6350">{{rfc|6350|title=XML Representation of vCard (xCard)}}</ref> such as Contact/DistributionList contain the version number in the x-kolab-version element which '''MUST''' be contained as top-level element directly in the vcard element
* Custom Kolab Objects '''MUST''' contain the version number in the version attribute of the root element.

If no version number is present, the version of the implementation '''SHALL''' be assumed.

=== Version upgrades / Backwards Compatibilty ===

Minor version upgrades '''MUST''' be backwards compatible in terms that they '''MUST''' only add '''OPTIONAL''' values. This ensures that implementations using a newer versions of the format can still read file written by an older implementation.
Minor version upgrades '''MUST NOT''' remove '''OPTIONAL''' values or add/remove '''REQUIRED''' values.

An implementation '''MUST''' be able to read older versions of the format with the same major version number, meaning there is no conversion needed for minor format upgrades.
An implementation of an older version of the format '''MAY'' be able to read newer versions, but it doesn't have to preserve additional data from the newer version of the format (a read/write cycle of a new format with an old implementation will potentially result in data loss.).

== Implementation ==

To have one implementation which can be used by as many clients as possible libkolabxml will be developed. libkolabxml is a library written in C++ with bindings for PHP/Python and possibly further languages using [http://www.swig.org SWIG]<ref name="SWIG">[http://www.swig.org SWIG]</ref>.

=== Scope ===
* the serialization/deserialization from/to the xml string to/from the in memory representation
* ensuring that all written/read objects are structurally valid

The implementation doesn't provide any interpretation of the data.

=== Technology ===
Internally the serialization is based on [http://www.codesynthesis.com/products/xsd/ xsdcxx]<ref name="CodeSynthesis XSD Databinding">[http://www.codesynthesis.com/products/xsd/ xsdcxx]</ref> which internally uses the xerces validating xml parser. The databindings are based on XSD schemas partially kolab specific and partially provided by [http://www.calconnect.org/artifacts/ical-art.shtml calconnect]<ref name="CalConnect Code Artifacts Repository">[http://www.calconnect.org/artifacts/ical-art.shtml] iCalendar in XML Schema</ref>.

=== Version Upgrade ===

A simple upgrade of libkolabxml should provide an interactionless upgrade

=== Implementation limitations ===

Because the library validates the xml files, any unknown element will cause the validation to fail. This means even new optional element disable an older version of the library to read the document.


== Extensibility ==

The extensibilty mechanisms of xCal/xCard are not supported, unless the extension elements are added to the Kolab Format specifcation (and thus, it's implementation).

Vendors '''MAY''' extend the format on their own by making use of the optional [[#Kolab Custom Property]] which ensures backwards compatibility.

Vendors '''SHOULD''' add their extensions using a [[#Kolab XML Format Enhancement Proposal]] to the official Kolab XML Format so other Vendors can reuse the values.

=== Kolab Custom Property ===

  kolab-custom = x-custom {
    element identifier { [[#String]] },
    element value { [[#String]] }
  }

The element '''MUST NOT''' be added to elements other than the following:

* icalendar/vcalendar/properties
* vcard
* note
* configuration

The "x-custom" element '''MUST''' appear on toplevel within those elements, custom properties which are deeper within the structure are not supported.

The "x-custom" element contains two subelement only:
* "identifier": unique identifier used to identify custom property.
* "value": value of the custom property

Client implementatinos '''SHALL''' preserve all custom properties.

Example:

  <x-custom>
    <identifier>cusotomtypeidentifier</identifier>
    <value>customvalue</value>
  </x-custom>

=== Support of existing Extensions ===

The Kolab XML Format '''MAY''' be extended by adding new supported extensions to xCal/xCard objects or new elements to custom Kolab XML objects.
In order to do this, extensions '''MUST''' be added to the Kolab XML Format Specification first.
Extensions added to the Kolab XML Format are not subject to the limited extension approach as lined out above.

Extensions added to the Kolab XML Format '''MUST NOT''' introduce redundant data.

{{note|Example|For instance there exists X-KADDRESSBOOK-X-Anniversary and X-EVOLUTION-ANNIVERSARY. Only one of them or a new type MAY be added to the format.}}

=== Kolab XML Format Enhancement Proposal ===

A proposal to extend the Kolab XML Format should be sent to [mailto:kep-secretariat@lists.kolabsys.com kep-secretariat@lists.kolabsys.com].

A proposal '''SHALL''' have the following structure:

* Extension name: x-vendor-name

''Desired name of the extension''

* Structure:
  <x-vendor-name>
    <value1/>
    <value2/>
  </x-vendor-name>

''Description of the structure in XML, Relax NG or similar.''

* Example:
  <x-kolab-specialproperty>
    <value1>val1</value1>
    <value2>val2</value2>
  </x-kolab-specialproperty>

''A real world example how such an extension would look like.''

* Description:

''Exact description of the value and how it is used using the in {{rfc|2119}} <ref name="rfc2119">{{rfc|2119|title=Key words for use in RFCs to Indicate Requirement Levels}}</ref> defined keywords.''

* Rationale:

''A description why the value is needed.''

* Author:

'''Author of the application'''

This allows the Kolab Community to evaluate if the extension is reasonable and can't be modeled using the existing properties. The discussion '''SHALL''' take place on [mailto:kolab-format@kolab.org kolab-format@kolab.org].

{{note|Needs clarification|We need a defined process how to accept a format extension proposal and how we publish the new specification. A full KEP might be too slow but one possible solution.}}

== Upgrade Path ==

This KEP replaces the complete Kolab XML Format specification. Old implementations will not be able to read documents produced according to this specification.

== Rationale ==

{{note|XML Version|The XML version was changed to 1.0 for all objects. See <ref name="Dont use xml 1.1">[http://www.cafeconleche.org/books/effectivexml/chapters/03.html Dont use xml 1.1]</ref> for the reasons.}}

=== Overview ===

The current Kolab XML Format specification is for many problems not powerful enough, resulting in constant extension through KEPs. Further the specification is not very explicit about the value semantics, leading to a potential problems for interoperability and maintainability of the format.

The original motivation to create an own Kolab XML Format, the interoperability issues of iCal and vCard, still apply, but those specifications have improved since and the approach how to define this format has been reconsidered.
The recent release of the xCal/xCard specifications provide a good specification base for our format. The calendaring problem space is complex and it is very difficult to design a format from scratch which serves all current needs and is extensible in a sustainable manner. By using those RFCs as "framework" we can ensure that format can grow in a sustainable way, while we can start with only the needed subset of values.

Given that at least Kontact follows those specifications closely, making use of this format also makes the mapping to the UI a lot easier.

The process for this KEP evolved from the idea to have an XSD-binding based library for the old format to a complete redefinition of the format. Some key points which were evaluated, respectively some conclusions made in the process were:
* A pure XSD-based databinding in native languages is not enough because XSD is not expressive enough (cannot validate all constructs) and there is a lack of tools (i.e. for PHP)
* The current Kolab Format would have to be extended extensively in order to support all features of Kontact, resulting in something similar to existing standards
* We're so much bound to iCal/vCard by the client implementations that we can in fact not change much in the format without breaking a usecase (try to simplify recurrences and you'll see...). => The client UI defines our format (to some extent)
* Interoperability is not ensured by the format, there is still a lot of room for different interpretation on the interpretation layer. The format description therefore needs to go beyond what values are allowed and give descriptions of the value semantics and how clients should behave.
* The used RFCs have too many options and are thus never fully implemented.

While the used RFCs do provide a solid base for a format specification, they were never meant as storage format, but as a format for representation and transport. This becomes apparent in the flexiblity of the specifications, allowing often many different ways to do the same thing and providing a miriad of optional parameters. To be usable as a storage format, the Kolab XML Format specification provides the additional information/restrictions resulting in a sparse, canonical and normative format where every property serves a particular usecase.

This specification was designed to serve all currently existing usecases while allowing for future extensions. This means the properties are designed in a way that they don't serve any hypothethic usecase but rather existing ones, while being extensible in a way that the format can grow and support new usecases in a sustainable way. This way "dead-on-arrival" properties which serve no real usecase and have to be maintained for the lifetime of the format, can be avoided. The used RFCs provide an excellent "framework" for this task.

=== Interoperability ===

It was established that the existing iCal and vCard specifications suffer from interoperability issues, not because the specifications are bad, but because they are too flexible and too large to ever be fully implemented. This results in different clients speaking different "dialects" (subsets which are all conforming to iCal but incompatible to each other).

The approach the first Kolab XML Format version took, was to redefine the format from scratch, resulting in a simpler, actually implementable specification. It oversimplified some problems though, lacked a firm specification and finally didn't provide all features for the usecases of today.

By reusing the existing iCal/vCard specifications we can not only reuse the value semantics, which are difficult define, we can also use those specifications as framework within which our specification can grow according to our needs, while we can be sure that we are not oversimplifying a problem because the used RFCs make sure we can implement/model at least all their features.

By defining the Kolab XML Format as a fully RFC compliant subset, we ensure an implementable specification which provides additional specification where the RFC's are not exact enough or allow for too many options. This way the interoperability of the format is improved. By being RFC compliant, a sustainable format is ensured which should also lower the adoption barrier for other projects.

It is acknowledged that the format alone does not solve interoperability and that a system where different client implementations exchange data (such as Kolab) need a transformation layer which maps the values of the Kolab XML Format to the internally used values of each implementation. The Kolab XML Format specification provides the "common grounds" for these translation layers. A translation layer can appear in client implementations which implement the Kolab XML Format, or on a server where a CalDAV implementation can map Kolab XML Values to the respective "iCal dialect" the client speaks (iCal dialect because every implementation which uses iCal uses a slightly different subset of iCal).

This way we achieve a strict and exact definition of our format. By implementing the said translation layers we take control that can ensure true interoperability.

=== Date-Time format ===

* Local time with timezone information indicates that local time in a specific location is wanted
* Local time without timezone information indicates that local time in the current location is wanted (and that it should change with the location)
* UTC indicates that an absolute time is wanted which is not bound to locations or timezones.

Timezones are only referred to by identifier and not directly embedded, with the idea that the interpreting system can use updated timezone information. It is true that this results in information loss in terms that it is not known anymore to which UTC time the originally described time (using a timezone) originally resolved.
It is assumed that the intention of the user is to have an event at a certain time, no matter how the timezones changed. As an example:

Paul scheduled a meeting at 10:00 in Paris because he starts working at 8:00 in the office. If now the timezone had changed by one hour he still would want his meeting at 10:00 and not suddenly at 9:00 although that means the UTC time of the meeting has effectively changed. This is due to the fact that his daily schedule changes with changing timezones.

Therefore embedding the old timezone information, while preserving the originally intended UTC time, would work agains Paul's intention of having a meeting two hours after work.

UTC offset times are not used because they are an oversimplifaction of timezones.

[[KEP:2]] [http://wiki.kolab.org/KEP:2#Background_notes_on_design_decisions_and_backwards_compatibility Background notes on design decisions and backwards compatibility] explains this in further detail.

=== Reason for not implementing the default extensions mechanisms ===

The extension mechanisms provided by xCal/xCard are much to complicated to implement by allowing arbitrary content anywhere in the xml structure.
Since this data has to be stored by clients in their in-memory representation one would have to store xPath/value pairs, which could be inserted into the structure on writing.
Also the parser would have to check in every element if extension elements are nested, since there is no single defined place where extension elements are.
This is too complicated given that it hardly serves any usecase.

Using an XSD based databinding this feature is not even feasible (except by adding an xs:any element before and after every single element in the document).

With the restricted version, we can build data-bindings to access the data and can collect the custom element in on defined place.

Further, by restricting the extensibility, we encourage vendors to include their extensions into the official format, which is only benefical for the Kolab eco-system.

=== Reason for not using namespaces and the element name as identifier ===

Theoretically vendors could arbitrarily extend the format with elements of any name in a their own namespace. The problem with this is that all implementation need to be able to read the elements in order to preserve them.

=== Points of concern with the used RFC's ===

The main points of concern with the used RFC's are:
* extension mechanism
* interoperability
* no defined ordering

While the first two have been discussed already, the last needs some explanation. While there is a performance penalty in reading the elements without defined order (one has to potentially loop everytime through all elements before finding the right one, in the worst case), this is not the main concern. The main concern is that XSD does not allow to specify unordered content without a workaround, and with this workaround we loose complete control over cardinalities (how many times and if an element MUST appear). This is of course an implementation specific problem but since there doesn't seem to be any additional value in unordered content it's still at least a questionable design decision.

The said workaround is to make all types of the unordered list an extension of a "BaseType". If a list of this "BaseType" is defined, it is obviously possible to add elements of the type "BaseType" to the list in any order.

To fix this shortcoming of the used RFC's the order is required in the Kolab XML Format.

== References ==

{{Reflist}}

== Copyright ==

This document has been placed in the public domain.