KEP-0009.txt

Georg Greve greve at kolabsys.com
Fri Sep 2 16:59:41 CEST 2011


 KEP-0009.txt |   66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 61 insertions(+), 5 deletions(-)

New commits:
commit ffe01e571ff5279b0c19f46b87b4f658c2b1ebb6
Author: Georg Greve <greve at kolabsys.com>
Date:   Fri Sep 2 16:59:17 2011 +0200

    Namespace/scope limitation, annotation value clarifications and some rationale to document reasons for choices.

diff --git a/KEP-0009.txt b/KEP-0009.txt
index 79dd9e8..824024e 100644
--- a/KEP-0009.txt
+++ b/KEP-0009.txt
@@ -38,7 +38,29 @@ This is a '''new''' mechanism:
 
 The Kolab Groupware Solution currently does not make use of message annotations according to {{rfc|5257}} <ref name="rfc5257">{{rfc|5257|title=Internet Message Access Protocol - ANNOTATE Extension}}</ref>, but it has been argued that in some cases such annotations would be the most efficient approach, e.g. single-message encryption and ACL scenarios of groupware items. 
 
-As this mechanism is closely related on a conceptual level to the folder annotations according to RFC 5464 it shall inherit all the general rules for usage of RFC 5464 folder annotations defined below.
+==== Scope of these provisions ====
+
+The provisions set forth in this KEP '''MUST''' be followed for all annotations in the '/vendor/kolab/*' namespace.
+
+Third party annotations in different name spaces '''SHOULD''' follow these provisions, and '''MUST''' be documented by their provider in an informational KEP in order to become eligible for inclusion in the Kolab Groupware Server.
+
+=== Public and private annotations ===
+
+RFC 5257 provides means for public and private annotations. Both kinds MAY be used in the Kolab Groupware Solution, but use of each annotation MUST be defined in a single KEP for all prefixes.
+
+=== Values ===
+
+Simple values for both private and public annotations '''SHOULD''' be stored as UTF-8 encoded string whenever possible.
+
+Where array serialization or hashing is required because a value cannot be stored as plain text or contains illegal characters, values '''MUST''' be stored as UTF-8 encoded string according to {{rfc|4627}}<ref name="rfc4627">{{rfc|4627|title=The application/json Media Type for JavaScript Object Notation (JSON)}}</ref>, the JavaScript Object Notation (JSON).
+
+If that encoding cannot safely represent the value, Base64 encoded according to {{rfc|3548}} <ref name="rfc3548">{{rfc|3548|title=The Base16, Base32, and Base64 Data Encodings}}</ref> '''MAY''' be used, but its use is strongly discouraged.
+
+Other encodings '''MUST NOT''' be used.
+
+==== Background: Requirements by RFC 5257 ====
+
+Values '''MUST''' conform to the UTF-8 character set defined in {{rfc|3629}}<ref name="rfc3629">{{rfc|3629|title=UTF-8, a transformation format of ISO 10646}}</ref> as specified in RFC 5257<ref name="rfc5257" />.
 
 == Configuration storage in folder annotations ==
 
@@ -48,7 +70,15 @@ This is a '''modificaton and clarification of an existing''' mechanism:
 
 From its inception in 2003 and up until and including Kolab Format 2.0, the Kolab Groupware Solution has been using [http://tools.ietf.org/html/draft-daboo-imap-annotatemore-05 draft version 5 of the ANNOTATEMORE proposal] which has been finalized in February 2009 into the IMAP METADATA Extension defined in {{rfc|5464}} <ref name="rfc5464">{{rfc|5464|title=The IMAP METADATA Extension}}</ref>. 
 
-With application of this changeset against the Kolab Format 2.0, all clients '''MUST''' conform to {{rfc|5464}} '''only'''. Usage of ANNOTATEMORE will be deprecated, unsupported and not compliant with the Kolab Format resulting from application of this changeset.
+With application of this changeset against the Kolab Format 2.0, all clients '''MUST''' conform to {{rfc|5464}} '''only'''. 
+
+Usage of ANNOTATEMORE will be deprecated, unsupported and not compliant with the Kolab Format resulting from application of this changeset.
+
+==== Scope of these provisions ====
+
+The provisions set forth in this KEP '''MUST''' be followed for all annotations in the '/vendor/kolab/*' namespace.
+
+Third party annotations in different name spaces '''SHOULD''' follow these provisions, and '''MUST''' be documented by their provider in an informational KEP in order to become eligible for inclusion in the Kolab Groupware Server.
 
 === Public and private annotations ===
 
@@ -56,11 +86,25 @@ RFC 5464 provides means for public and private annotations. Both kinds MAY be us
 
 === Values ===
 
-Simple values for both private and public annotations SHOULD be plain text whenever possible.
+Simple values for both private and public annotations '''SHOULD''' be stored as UTF-8 encoded string whenever possible.
+
+Where array serialization or hashing is required because a value cannot be stored as plain text or contains illegal characters, values '''MUST''' be stored as UTF-8 encoded string according to {{rfc|4627}}<ref name="rfc4627">{{rfc|4627|title=The application/json Media Type for JavaScript Object Notation (JSON)}}</ref>, the JavaScript Object Notation (JSON). 
+
+If that encoding cannot safely represent the value, Base64 encoded according to {{rfc|3548}} <ref name="rfc3548">{{rfc|3548|title=The Base16, Base32, and Base64 Data Encodings}}</ref> '''MAY''' be used, but its use is strongly discouraged.
+
+Other encodings '''MUST NOT''' be used.
+
+==== Background: Requirements by RFC 5464 ====
+
+RFC 5464<ref name="rfc5464" /> inherits the Augmented Backus-Naur Form (ABNF, {{rfc|5234}}<ref name="rfc5234">{{rfc|5234|title=Augmented BNF for Syntax Specifications: ABNF}}</ref>) including definitions from {{rfc|3501}}<ref name="rfc3501">{{rfc|3501|title=INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1}}</ref> superseded by {{rfc|4466}}<ref name="rfc4466">{{rfc|4466|title=Collected Extensions to IMAP4 ABNF}}</ref>. 
+
+In this notation, value is specified in RFC 5464 as
 
-Where array serialization or hashing is required because a value cannot be stored as plain text or contains illegal characters, values MUST be stored according to {{rfc|4627}}<ref name="rfc4627">{{rfc|4627|title=The application/json Media Type for JavaScript Object Notation (JSON)}}</ref>, the JavaScript Object Notation (JSON).
+   value          =  nstring / literal8
 
-No other encoding MUST be used.
+which allows representation as string or binary value as detailed in {{rfc|3516}}<ref name="rfc3516">{{rfc|3516|title=IMAP4 Binary Content Extension}}</ref>.
+
+{{note|Rationale|For the rationale of defining the allowed values in a way that is more limited than what the RFC allows, please see the section '[[#Rationale_on_encoding_for_values_of_RFC_5257_and_RFC_5464_annotations|Rationale on encoding for values of RFC 5257 and RFC 5464 annotations]]' below.}}
 
 == Configuration storage in XML objects ==
 
@@ -121,6 +165,8 @@ This KEP adds new functionality and folder types that will not be understood by
 
 == Rationale ==
 
+=== Overview ===
+
 There have been repeated discussions about how and where to store configuration for application specific settings in the Kolab Groupware Solution. In some cases, these ended up in annotations themselves (e.g. Z-Push configuration <ref name"zpc">Z-Push Configuration Details: [[Z_push:Configuration]]</ref>) in other cases they ended up in LDAP (e.g. free/busy list generation interval). Some scenarios have thus far only been theoretically examined, e.g. use of individual message annotations.
 
 Any such choice has advantages and disadvantages, specific properties that make it well suited for one, but not another scenario, e.g. offline storage yes/no, ability to share with others, ability to be determined by admin without user influence, and so on and so forth.
@@ -129,6 +175,16 @@ So the Kolab Community has come to understand it needs a toolset of approaches t
 
 The resulting set of four clearly defined mechanisms that can be mixed, matched and applied to the various scenarios should result in an encompassing set of options while ensuring these are used '''consistently''' across scenarios to simplify the life of all participants in the community.
 
+=== Rationale on encoding of values for RFC 5257 and RFC 5464 annotations ===
+
+As the sections [[#Background:_Requirements_by_RFC_5257|Background: Requirements by RFC 5257]] and [[#Background:_Requirements_by_RFC_5464|Background: Requirements by RFC 5464]] demonstrate, values for these annotations have different requirements: RFC 5257 specifies UTF-8 text, RFC 5464 allows strings or binary data.
+
+Because annotations according to RFC 5257 and RFC 5464 are conceptually very similar, we aim to unify the practical aspects of their use as much as possible. Identical rules for values to be stored is a step in that direction and the provisions in this KEP should be sufficiently wide to allow for efficient usage in all kinds of scenarios.
+
+Explicitly choosing the JavaScript Object Notation (JSON)<ref name="rfc4627" /> for encoding complex values also comes from the same background. Unlike other serializations which are often dependent upon a particular programming language, JSON encoding is equally available in a wide range of languages. Furthermore its default output is defined as UTF-8, thus matching the character range of the more limited of the two annotations, RFC 5257. The JSON specification also allows for UTF-16LE, UTF-32LE, UTF-16BE encoding in principle, but these have been excluded by an explicit selection of UTF-8 for the JSON encoding in the normative section of this KEP.
+
+Where that encoding is insufficient for reasons unforeseeable during the drafting of this KEP, Base64 encoding is also allowed in order to wrap whatever else we might need to store. It should be noted however that at the current point in time it is not clear why Base 64 should ever be used in practice.
+
 == References ==
 
 {{Reflist}}





More information about the commits mailing list