Encoding exceptions (cloudevents#322)

* Special encodings for extensions Signed-off-by: Clemens Vasters <[email protected]> * Special encodings for extensions in transports Signed-off-by: Clemens Vasters <[email protected]> * RFC2119 errors Signed-off-by: Clemens Vasters <[email protected]>
ssrdjan-fadv · Oct 15, 2018 · 7ac6408 · 7ac6408
1 parent 1e127a2
commit 7ac6408
Show file tree

Hide file tree

Showing 5 changed files with 70 additions and 18 deletions.
diff --git a/amqp-format.md b/amqp-format.md
@@ -50,7 +50,8 @@ system, which this mapping leans on.
 
 ### 2.2. Type System Mapping
 
-The CloudEvents type system is mapped to AMQP types as follows:
+The CloudEvents type system MUST be mapped to AMQP types as follows,
+with exceptions noted below.
 
 | CloudEvents | AMQP
 |-------------|-------------------------------------------------------------
@@ -61,6 +62,19 @@ The CloudEvents type system is mapped to AMQP types as follows:
 | Map         | [map][AMQP-Map]
 | Any         | See 2.3.
 
+Extension specifications MAY define diverging mapping rules for the values of
+attributes they define.
+
+For instance, the attribute value may be a data structure
+defined in a standard outside of CloudEvents, with a formal AMQP mapping, and
+there might be risk of translation errors or information loss when the original
+format is not preserved.
+
+An extension specification that defines a diverging mapping rule for AMQP,
+and any revision of such a specification, MUST also define explicit mapping
+rules for all other event formats that are part of the CloudEvents core at
+the time of the submission or revision.
+
 ### 2.3. Mapping Any-typed Attributes
 
 `Any`-typed CloudEvents values can either hold a `String`, or a `Binary`

diff --git a/amqp-transport-binding.md b/amqp-transport-binding.md
@@ -150,8 +150,20 @@ The [`data` attribute](#22-data-attribute) byte-sequence is used as the AMQP
 #### 3.1.3. Metadata Headers
 
 All [CloudEvents][CE] attributes with exception of `contentType` and `data`
-are individually mapped to and from the AMQP
-[application-properties][app-properties] section.
+MUST be individually mapped to and from the AMQP
+[application-properties][app-properties] section, with exceptions noted
+below.
+
+CloudEvents extensions that define their own attributes MAY define a
+diverging mapping to AMQP properties for those attributes, also in 
+different message sections, especially if specific attributes or their 
+names need to align with AMQP features or with other specifications that 
+have explicit AMQP header bindings.
+
+An extension specification that defines a diverging mapping rule for AMQP,
+and any revision of such a specification, MUST also define explicit mapping
+rules for all other transport bindings that are part of the CloudEvents core at
+the time of the submission or revision.
 
 ##### 3.1.3.1 AMQP Application Property Names
 

diff --git a/http-transport-binding.md b/http-transport-binding.md
@@ -154,7 +154,18 @@ message body.
 #### 3.1.3. Metadata Headers
 
 All [CloudEvents][CE] attributes with exception of `contentType` and `data`
-are individually mapped to and from distinct HTTP message headers.
+MUST be individually mapped to and from distinct HTTP message headers,
+with exceptions noted below.
+
+CloudEvents extensions that define their own attributes MAY define a 
+diverging mapping to HTTP headers for those attributes, especially if 
+specific attributes need to align with HTTP features or with 
+other specifications that have explicit HTTP header bindings. 
+
+An extension specification that defines a diverging mapping rule for HTTP,
+and any revision of such a specification, MUST also define explicit mapping
+rules for all other transport bindings that are part of the CloudEvents core at
+the time of the submission or revision.
 
 ##### 3.1.3.1 HTTP Header Names
 
@@ -174,13 +185,6 @@ of HTTP headers, where by the name of each header carries the prefix
 "CE-", an infix reflecting the map attribute followed by a dash 
 ("-"), and the name of the map entry key, e.g. "CE-attrib-key".
 
-CloudEvents extensions that define their own attributes MAY define a 
-diverging mapping to HTTP headers for those attributes, especially if 
-specific header names need to align with HTTP features or with 
-other specifications that have explicit HTTP header bindings. If specific
-names are not required, extensions SHOULD follow the naming convention
-cited here.
-
 Note: per the [HTTP](https://tools.ietf.org/html/rfc7230#section-3.2)
 specification, header names are case-insensitive.
 

diff --git a/json-format.md b/json-format.md
@@ -40,20 +40,20 @@ interpreted as described in [RFC2119][RFC2119].
 
 This section defines how CloudEvents attributes are mapped to JSON. This
 specification does not explicitly map each attribute, but
-provides a generic mapping model that applies to all current and future 
+provides a generic mapping model that applies to all current and future
 CloudEvents attributes, including extensions.
 
-
 ### 2.1. Base Type System
 
 The core [CloudEvents specification][CE] defines a minimal abstract type
 system, which this mapping leans on.
 
 ### 2.2. Type System Mapping
 
-The CloudEvents type system is mapped to JSON types as follows:
+The CloudEvents type system MUST be mapped to JSON types as follows, with
+exceptions noted below.
 
-| CloudEvents | JSON
+| CloudEvents  | JSON
 |--------------|-------------------------------------------------------------
 | String       | [string][JSON-String]
 | Binary       | [string][JSON-String], [Base64-encoded][base64] binary
@@ -62,6 +62,19 @@ The CloudEvents type system is mapped to JSON types as follows:
 | Map          | [JSON object][JSON-Object]
 | Any          | [JSON value][JSON-Value]
 
+Extension specifications MAY define diverging mapping rules for the values of
+attributes they define.
+
+For instance, the attribute value might be a data structure
+defined in a standard outside of CloudEvents, with a formal JSON mapping, and
+there might be risk of translation errors or information loss when the original
+format is not preserved.
+
+An extension specification that defines a diverging mapping rule for JSON,
+and any revision of such a specification, MUST also define explicit mapping
+rules for all other event formats that are part of the CloudEvents core at
+the time of the submission or revision.
+
 ### 2.3. Mapping Any-typed Attributes
 
 The CloudEvents `data` attribute is `Any`-typed, meaning that it either
@@ -97,12 +110,11 @@ The following table shows exemplary mappings:
 The CloudEvents [JSONSchema](http://json-schema.org) for the spec is located
 [here](spec.json) and contains the definitions for validating events in JSON.
 
-
 ## 3. Envelope
 
 Each CloudEvents event can be wholly represented as a JSON object.
 
-Such a representation uses the media type `application/cloudevents+json`
+Such a representation uses the media type `application/cloudevents+json`.
 
 All REQUIRED and all not omitted OPTIONAL attributes in the given event MUST
 become members of the JSON object, with the respective JSON object member name

diff --git a/mqtt-transport-binding.md b/mqtt-transport-binding.md
@@ -152,7 +152,17 @@ payload of the MQTT PUBLISH message.
 
 All [CloudEvents][CE] attributes with exception of `contentType` and `data`
 MUST be individually mapped to and from the User Property fields in the MQTT
-PUBLISH message.
+PUBLISH message, with exceptions noted below.
+
+CloudEvents extensions that define their own attributes MAY define a 
+diverging mapping to MQTT user properties or features for those attributes, 
+especially if specific attributes need to align with MQTT features, or with 
+other specifications that have explicit MQTT header bindings.
+
+An extension specification that defines a diverging mapping rule for MQTT,
+and any revision of such a specification, MUST also define explicit mapping
+rules for all other transport bindings that are part of the CloudEvents core at
+the time of the submission or revision.
 
 ##### 3.1.3.1 User Property Names