summaryrefslogtreecommitdiff
path: root/KEP-0017.txt
diff options
context:
space:
mode:
authorChristian Mollekopf <chrigi_1@fastmail.fm>2011-12-12 12:38:17 (GMT)
committerChristian Mollekopf <chrigi_1@fastmail.fm>2011-12-12 12:38:17 (GMT)
commit885311648d3ad267b007a62dbe14828aedd2115d (patch)
tree61a5a4cbf14532289fd35de90d139505e3279922 /KEP-0017.txt
parentee218caaf0a11103f73159d3ac2580fa823c0233 (diff)
downloadkeps-885311648d3ad267b007a62dbe14828aedd2115d.tar.gz
initial draft of KEP:17
Diffstat (limited to 'KEP-0017.txt')
-rw-r--r--KEP-0017.txt1889
1 files changed, 1889 insertions, 0 deletions
diff --git a/KEP-0017.txt b/KEP-0017.txt
new file mode 100644
index 0000000..3fe00ad
--- /dev/null
+++ b/KEP-0017.txt
@@ -0,0 +1,1889 @@
+{{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=
+ |obsolets=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.
+
+{{note|Needs Clarification: IMAP Folder|Do we need to specify in which folder the individual objects may be stored? I consider this out of the scope of this KEP.}}
+
+== 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]] )
+
+''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.
+
+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.
+
+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]] )
+
+''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-productid = ( "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 servers 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}}
+
+==== 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 ====
+
+===== Related-to =====
+
+ property-relatedto = element related-to {
+ element 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.''
+
+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.
+
+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 shows up in freebusy time searches.''
+
+* "OPAQUE": The event is visible in freebusy time searchs.
+* "TRANSPARENT": The event is invisible in freebusy time searchs.
+
+If not specified this property '''SHALL''' default to "OPAQUE".
+
+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.
+
+Implements:
+* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.7.4 section-3.8.7.4]
+
+{{note|Needs clarification: Relevance|Its set by korganizer but whats the usecase? It is used in recurrence id matching to identify the exactly same instance (I believe). The last modification date should be enought though.}}
+
+===== Recurrences =====
+
+The complete set of recurrences '''MUST''' be derived using the [[#Start date]], [[#Recurrence rule]], [[#Recurrence date]] and [[#Exception date]] properties.
+
+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.
+
+{{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")
+
+ 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 { [[#Integer|xsd:integer]] ?, type-weekday }*,
+ 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]
+
+{{note|Needs clarification: Period| Is the period type used to alter the duration of a single recurrence? }}
+
+====== 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 (highest) to 9 (lowest).
+
+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|structure|This should probably go to a more generic part}}
+
+{{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 cal-address { [[#Mailto URL]] }
+ }
+
+''The organizer of the incidence.''
+
+The cal-address '''MUST''' be a [[#Mailto URL]] email address.
+
+* 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]
+
+===== Contact =====
+
+ property-contact = element contact {
+ element parameters {
+ element x-uid { [[#UID]] } ?
+ } ?,
+ element text { [[#String]] }
+ }
+
+''A contact related to the incidence.''
+
+The text property '''SHOULD''' contain the name of the contact.
+
+* "x-uid": This parameter '''MAY''' be used to refer to the [[#Contact]] object of the contact. This parameter '''MUST''' contain the [[#UID]] of a [[#Contact]] if specified.
+
+Implements:
+* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.4.2 section-3.8.4.2]
+
+{{note|Needs clarification: Useless?|not sure if we need this property (dont know where it is used).}}
+{{note|Needs clarification: x-uid|not sure if the x-uid is valid, see attendee. Specifying the uid separately helps clients to display something if they are not able to lookup the other contact.}}
+
+===== 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 x-uid { [[#UID]] } ?
+ }?,
+ element cal-address { [[#Mailto URL]] }
+ }
+
+''An attendee of an event.''
+
+The cal-address '''MUST''' be a [[#Mailto URL]] email address.
+
+* "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.
+* "x-uid": This propery may '''MAY''' be used to refer to the [[#Contact]] object of the attendee. The x-uid '''MUST''' contain the [[#UID]] of a [[#Contact]] if specified.
+
+Implements:
+* {{rfc|5545}} [https://tools.ietf.org/html/rfc5545#section-3.8.4.1 section-3.8.4.1]
+
+{{note|Needs clarification: x-uid param| instead of cal-address as uid? This is what kontact does with X-UID=30f35c1792c219de35c07d91456f1208 used in kontact. x-uid might not work this way because kontact uses the internal uid in this field.}}
+{{note|Needs clarification: LDAP|There would be an additonal dir parameter for an ldap uri available. useful?}}
+{{note|Needs clarification: cutype|For "resource" role? i.e. a meeting room. Currently this is not possible and it was in the old format specification. But I don't know if this is used anywhere.}}
+
+===== 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]
+
+==== 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 URL]] } } +,
+ 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/repeat":
+
+ type-audioprop = element properties {
+ element action { text { "AUDIO" } },
+ property-trigger,
+ element attach { [[#Attachment]] } ?
+ (
+ 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|RFC conflict|ical says there MUST be a summary for the email alarm and xCal doesnt even allow it (also some other properties are mixed up between email and disp). An erratum has been submitted.}}
+{{note|Needs clarification: X-KDE-KCALCORE-ENABLED|what is it good for and how can we model it? X-KDE-KCALCORE-ENABLED:TRUE}}
+
+==== Todo ====
+
+ todo = element vtodo {
+ element properties {
+ element uid { [[#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]] } +
+ }?
+ }
+
+{{note|Needs clarification: f/b|transp does not apply to todo, do we need showe-time-as form the old format spec?}}
+
+''An object representing a task/todo.''
+
+* Content-MimeType: 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]
+
+==== Event ====
+
+ event = element vevent {
+ element properties {
+ element uid { [[#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]] } +
+ }?
+ }
+
+{{note|Needs clarification: transp|tranp has only TRANSPARENT or OPAQUE as state to differentiate if it should show up in F/B, but show-time-as is one of free, tentative, busy, or outofoffice. Not sure what show-time-as is good for though}}
+
+''An object representing an event.''
+
+* Content-MimeType: 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]] },
+ element created { [[#Creation Date]] },
+ element dtstamp { [[#Last modification date]] },
+ element sequence { [[#Sequence]] }, ?
+ element class { [[#Classification]] } ?,
+ element categories { [[#Categories]] } ?,
+ element dtstart { [[#Start date]] } ?,
+ element dtend { [[#End date]] } ? |
+ element contact { [[#Contact]] } *,
+ element attendee { [[#Attendee]] } *,
+ element attach { [[#Attachment]] } *,
+ element x-custom { [[#Kolab Custom Property]] } *
+ }
+ }
+
+{{note|Needs clarification: Contact|Looks like a nice to have, but who really uses it? not kontact.}}
+
+An object representing an journal entry. Journal entries '''SHALL''', as opposed to notes, be related to a calendar date.
+
+* Content-MimeType: 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?}}
+
+===== 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].
+
+{{note|Implementation note|This corresponds to kaddressbooks business tab}}
+{{note|Needs clarification: name element|maybe the name element should be used for identification of the affiliation instead (not sure if this is actually necessary). If all implementations just support multiple generic affiliations its not needed, but if i.e. one supports multiple affiliations and kontact only supports a business affiliation kontact could identify the business affiliation based on the name (although thats likely to break when used this way)}}
+
+====== Organization ======
+
+ property-org = element org {
+ element text { [[#String]] } +
+ }
+
+''A organization associated with the contact''
+
+A contact '''MAY''' be associated with multiple organizations by using multiple org properties.
+
+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|Needs clarification: 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 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 (thats how its used in kontact)}}
+
+====== Title ======
+
+ property-title = element title {
+ element text { [[#String]] }
+ }
+
+''Specifies a position or job of the contact within the organization.''
+
+Implements:
+* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.6.1 section-6.6.1]
+
+====== Manager ======
+
+ property-manager = element x-manager {
+ element text { [[#String]] }
+ }
+
+''Specifies a manager of the contact within the organization.''
+
+{{note|Needs clarification: related|could be expressed using a related property}}
+
+====== Assistant ======
+
+ property-assistant = element x-assistant {
+ element text { [[#String]] }
+ }
+
+''Specifies a manager of the contact within the organization.''
+
+{{note|Needs clarification: related|could be expressed using a related property}}
+
+====== Office ======
+
+ property-assistant = element x-office {
+ element text { [[#String]] }
+ }
+
+''Additional information related to the office, such as it's location.''
+
+{{note|Implementation note|This property is somewhat redunant to Address but KAddressbook provides 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.}}
+
+===== 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.''
+
+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.
+
+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"
+ } +
+ }?
+ }?,
+ ( element uri { [[#URI|xsd:anyURI]] } | element text { [[#String]] } )
+ }
+
+''Specifies a relation of the contact to another contact.''
+
+Types:
+* "spouse": Specifies that the related contact is the spouse of this contact.
+* "child": Specifies that the related contact is the child of this contact.
+
+Implements:
+* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.6.6 section-6.6.6]
+
+{{note|Needs clarification: uri|maybe we should us x-uid instead of uri as well which can be specified additionally to the text. This way clients which dont support getting the name from a nother object can still display the name.}}
+{{note|Needs clarification: manager/assistat|extend for manager and assistant (in which case this should be added to the affiliation group as well? This would obsolete the x-manager x-assistant properties}}
+
+===== 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|Needs clarification|Do we need a "application type" field? That information should be part of the uri I suppose.}}
+
+===== 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]
+
+===== Crypto =====
+
+ property-crypto = element x-crypto {
+ element allowed { element text { "PGP/INLINE" | "PGP/MIME" | "S/MIME" | "S/MIMEOpaque" }* },
+ element pgpkey {
+ element uri { [[#URI inline encoding]] }
+ } ?,
+ element smimekey {
+ element uri { [[#URI inline encoding]] }
+ } ?,
+ 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.
+* "pgpkey": Specifies a public key or authentication certificate associated with the contact. This key ''MAY'' be used to encrypt or sign using OpenPGP. The embedded key '''MUST''' have the type "application/pgp-keys".
+* "smimekey": Specifies a public key or authentication certificate associated with the contact. This key ''MAY'' be used to encrypt or sign using S/MIME. The embedded key '''MUST''' have the type "application/pkcs7-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)}}
+
+===== Member =====
+
+ property-member = element member {
+ element uri { [[#Mailto URL]] }
+ }
+
+''A member of the distribution list.''
+
+A member '''MUST''' contain a [[#Mailto URL]].
+
+The name of the member '''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].
+In case the name is included, URL-reserved characters '''MUST''' be encoded.
+
+Example:
+
+ mailto:John%20Doe%3cjdoe@example.com%3e
+
+ <member>
+ <uri>"mailto:John%20Doe%3cjdoe@example.com%3e"</uri>
+ </member>
+
+Implements:
+* {{rfc|6350}} [https://tools.ietf.org/html/rfc6350#section-6.6.5 section-6.6.5]
+
+==== Contact ====
+
+ contact = element vcard {
+ element uid { [[#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 group {
+ attribute name { [[#Affiliation|"Affiliation"]] },
+ element org { [[#Organization]] },
+ element logo { [[#Logo]] },
+ element title { [[#Title]] } *,
+ element role { [[#Role]] } *,
+ element x-manager { [[#Manager]] } *,
+ element x-assistant { [[#Assistant]] } *,
+ element x-office { [[#Office]] } *
+ } *,
+ 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 x-crypto { [[#Crypto]] },
+ element x-custom { [[#Kolab Custom Property]] } *
+ }
+
+''An address book entry for a contact.''
+
+* Content-MimeType: 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|Needs clarification: Attachment| Do we need an attachment property? There is none in the RFC and RC and KAddressbook dont use attachments for contacts}}
+
+==== Distribution List ====
+
+ distlist = element vcard {
+ element uid { [[#UID|uid]] },
+ element x-kolab-version { [[#Kolab XML Version]] },
+ element prodid { [[#Product ID]] },
+ element rev { [[#Last modified date]] },
+ element kind { [[#Kind|"group"]] },
+ element fn { [[#Name]] },
+ element member { [[#Member]] } *,
+ element x-custom { [[#Kolab Custom Property]] } *
+ }
+
+''A distribution list mostly used for emailing.''
+
+* Content-MimeType: application/vcard+xml
+* X-Kolab-Type: application/x-vnd.kolab.contact.distlist
+
+The vcard:kind element '''MUST''' have the value "group".
+
+=== Note ===
+
+ note = element note {
+ attribute version { [[#Kolab XML Version]] },
+ element uid { [[#UID|uid]] },
+ element prodid { [[#Product ID]] },
+ element creation-date { [[#Creation date]] },
+ element last-modification-date { [[#Last modified date]] },
+ element categories { [[#Categories]] } *,
+ element classification { [[#Classification]] } ?,
+ element attachment { [[#Attachment]] } *,
+ element summary { [[#Summary]] } ?,
+ element description { [[#Description] } ?,
+ element color { [[#Note Color]] } ?,
+ element x-custom { [[#Kolab Custom Property]]} *
+ }
+
+''A generic note, not necessarily associated with a specific date.''
+
+* Content-MimeType: application/x-vnd.kolab.*
+* X-Kolab-Type: application/x-vnd.kolab.note
+
+{{note|Needs clarfication: colors|do we need the color property? }}
+{{note|structure: attachment|Points to an xCal property? Maybe move the attachment to the generic section.}}
+
+==== Properties ====
+
+===== Note Color =====
+
+ property-color = element color {
+ attribute type { "foreground" | "background" },
+ [[#Color]]
+ }
+
+''Specifies color properties of the note.''
+
+The following color types are defined:
+* "foreground": Foreground color of the note (Text color).
+* "background": Background color of the note.
+
+=== Configuration ===
+
+ configuration = element configuration {
+ attribute version { [[#Kolab XML Version]] },
+ element uid { [[#UID|uid]] },
+ element prodid { [[#Product ID]] },
+ element creation-date { [[#Creation date]] },
+ element last-modification-date { [[#Last modified date]] },
+ element type { [[#String]] },
+ configurationtype-fields
+ }
+
+''A Kolab configuration object.''
+
+* Content-MimeType: application/x-vnd.kolab.configuration
+* 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 = xsd:string { pattern = "\d\d\d\d\d\d\d\dT\d\d\d\d\d\d" }
+
+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.
+
+==== 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>20110517T143000</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 URL ====
+
+A mailto url '''MUST''' conform to {{rfc|6068}}<ref name="rfc6068">{{rfc|6068}} The 'mailto' URI Scheme</ref>.
+
+==== 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.