remove dataencoding and intro data_base64 in JSON (cloudevents#492)

* Changed datacontentencoding to dataencoding Signed-off-by: Clemens Vasters <[email protected]> * remove dataencoding and intro data_base64 in JSON Signed-off-by: Clemens Vasters <[email protected]> * Consolidated handling of "data" in the JSON spec Signed-off-by: Clemens Vasters <[email protected]> * Link fix Signed-off-by: Clemens Vasters <[email protected]> * link fix Signed-off-by: Clemens Vasters <[email protected]>
catkins-miso · Sep 5, 2019 · 2c13c10 · 2c13c10
1 parent 4783a6d
commit 2c13c10
Show file tree

Hide file tree

Showing 5 changed files with 34 additions and 82 deletions.
diff --git a/adapters/aws-s3.md b/adapters/aws-s3.md
@@ -16,7 +16,6 @@ same pattern as described in the following table:
 | `source`              | "eventSource" value + `.` + "awsRegion" value + `.` + "s3.buckets.name" value  |
 | `specversion`         | `0.4-wip`                                       |
 | `type`                | `com.amazonaws.s3.` + "eventName" value         |
-| `datacontentencoding` | Omit                                            |
 | `datacontenttype`     | S3 event type (e.g. `application/json`)         |
 | `dataschema`          | Omit                                            |
 | `subject`             | "s3.object.key" value                           |

diff --git a/adapters/gitlab.md b/adapters/gitlab.md
@@ -18,7 +18,6 @@ based on the specified event.
 | `source`              | "repository.homepage" value              |
 | `specversion`         | `0.4-wip`                                |
 | `type`                | `com.gitlab.push`                        |
-| `datacontentencoding` | Omit                                     |
 | `datacontenttype`     | `application/json`                       |
 | `dataschema`          | Omit                                     |
 | `subject`             | "checkout_sha" value                     |
@@ -33,7 +32,6 @@ based on the specified event.
 | `source`              | "repository.homepage" value              |
 | `specversion`         | `0.4-wip`                                |
 | `type`                | `com.gitlab.tag_push`                    |
-| `datacontentencoding` | Omit                                     |
 | `datacontenttype`     | `application/json`                       |
 | `dataschema`          | Omit                                     |
 | `subject`             | "ref" value                              |
@@ -48,7 +46,6 @@ based on the specified event.
 | `source`              | "repository.homepage" value                           |
 | `specversion`         | `0.4-wip`                                             |
 | `type`                | `com.gitlab.issue.` + "object_attributes.state" value |
-| `datacontentencoding` | Omit                                                  |
 | `datacontenttype`     | `application/json`                                    |
 | `dataschema`          | Omit                                                  |
 | `subject`             | "object_attributes.iid" value                         |
@@ -63,7 +60,6 @@ based on the specified event.
 | `source`              | "commit.url" value                       |
 | `specversion`         | `0.4-wip`                                |
 | `type`                | `com.gitlab.note.commit`                 |
-| `datacontentencoding` | Omit                                     |
 | `datacontenttype`     | `application/json`                       |
 | `dataschema`          | Omit                                     |
 | `subject`             | "object_attributes.id" value             |
@@ -78,7 +74,6 @@ based on the specified event.
 | `source`              | "object_attributes.url" value, without the `#note\_...` part |
 | `specversion`         | `0.4-wip`                                                    |
 | `type`                | `com.gitlab.note.merge_request`                              |
-| `datacontentencoding` | Omit                                                         |
 | `datacontenttype`     | `application/json`                                           |
 | `dataschema`          | Omit                                                         |
 | `subject`             | "object_attributes.id" value                                 |
@@ -93,7 +88,6 @@ based on the specified event.
 | `source`              | "object_attributes.url" value without the `#note\_...` part |
 | `specversion`         | `0.4-wip`                                                   |
 | `type`                | `com.gitlab.note.issue`                                     |
-| `datacontentencoding` | Omit                                                        |
 | `datacontenttype`     | `application/json`                                          |
 | `dataschema`          | Omit                                                        |
 | `subject`             | "object_attributes.id" value                                |
@@ -108,7 +102,6 @@ based on the specified event.
 | `source`              | "object_attributes.url" value without the `#note\_...` part |
 | `specversion`         | `0.4-wip`                                                   |
 | `type`                | `com.gitlab.note.snippet`                                   |
-| `datacontentencoding` | Omit                                                        |
 | `datacontenttype`     | `application/json`                                          |
 | `dataschema`          | Omit                                                        |
 | `subject`             | "object_attributes.id" value                                |
@@ -123,7 +116,6 @@ based on the specified event.
 | `source`              | "repository.homepage" value                                    |
 | `specversion`         | `0.4-wip`                                                      |
 | `type`                | `com.gitlab.merge_request.` + "object_attributes.action" value |
-| `datacontentencoding` | Omit                                                           |
 | `datacontenttype`     | `application/json`                                             |
 | `dataschema`          | Omit                                                           |
 | `subject`             | "object_attributes.iid" value                                  |
@@ -138,7 +130,6 @@ based on the specified event.
 | `source`              | "project.web_url" value                                    |
 | `specversion`         | `0.4-wip`                                                  |
 | `type`                | `com.gitlab.wiki_page.` + "object_attributes.action" value |
-| `datacontentencoding` | Omit                                                       |
 | `datacontenttype`     | `application/json`                                         |
 | `dataschema`          | Omit                                                       |
 | `subject`             | "object_attributes.slug" value                             |
@@ -153,7 +144,6 @@ based on the specified event.
 | `source`              | "project.web_url" value                                   |
 | `specversion`         | `0.4-wip`                                                 |
 | `type`                | `com.gitlab.pipeline.` + "object_attributes.status" value |
-| `datacontentencoding` | Omit                                                      |
 | `datacontenttype`     | `application/json`                                        |
 | `dataschema`          | Omit                                                      |
 | `subject`             | "object_attributes.id" value                              |
@@ -168,7 +158,6 @@ based on the specified event.
 | `source`              | "repository.homepage" value              |
 | `specversion`         | `0.4-wip`                                |
 | `type`                | `com.gitlab.job.` + "job_status" value   |
-| `datacontentencoding` | Omit                                     |
 | `datacontenttype`     | `application/json`                       |
 | `dataschema`          | Omit                                     |
 | `subject`             | "job_id" value                           |

diff --git a/json-format.md b/json-format.md
@@ -89,16 +89,9 @@ inference using the rules from the mapping table, whereby the only potentially
 ambiguous JSON data type is `string`. The value is compatible with the
 respective CloudEvents type when the mapping rules are fulfilled.
 
-### 2.3. Mapping Data
+### 2.3. Examples
 
-If an implementation determines that the actual type of `data` is a `String`,
-the value MUST be represented as [JSON string][json-string] expression; for
-`Binary`, the value MUST represented as [JSON string][json-string] expression
-containing the [Base64][base64] encoded binary value.
-
-### 2.4. Examples
-
-The following table shows exemplary mappings:
+The following table shows exemplary attribute mappings:
 
 | CloudEvents     | Type          | Exemplary JSON Value            |
 | --------------- | ------------- | ------------------------------- |
@@ -108,11 +101,8 @@ The following table shows exemplary mappings:
 | id              | String        | "1234-1234-1234"                |
 | time            | Timestamp     | "2018-04-05T17:31:00Z"          |
 | datacontenttype | String        | "application/json"              |
-| data            | String        | "<much wow=\"xml\"/>"           |
-| data            | Binary        | "Q2xvdWRFdmVudHM="              |
-| data            | Map           | { "objA" : "vA", "objB", "vB" } |
 
-### 2.5. JSONSchema Validation
+### 2.4. JSONSchema Validation
 
 The CloudEvents [JSONSchema](http://json-schema.org) for the spec is located
 [here](spec.json) and contains the definitions for validating events in JSON.
@@ -128,38 +118,32 @@ become members of the JSON object, with the respective JSON object member name
 matching the attribute name, and the member's type and value being mapped using
 the [type system mapping](#22-type-system-mapping).
 
-### 3.1. Special Handling of "data"
+### 3.1. Handling of "data"
 
-The mapping of `data` follows the rules laid out in
-[Section 2.3.](#23-mapping-data), with two additional rules:
+Before taking action, a JSON serializer MUST first determine the runtime data 
+type of the `data` content.  
 
-First, if an implementation determines that the type of `data` is
-`Binary` or `String`, it MUST inspect the `datacontenttype` attribute to
-determine whether it is indicated that the data value contains JSON data.
+If the implementation determines that the type of `data` is `Binary`, the value
+MUST be represented as a [JSON string][json-string] expression containing the 
+[Base64][base64] encoded binary value, and use the member name `data_base64`
+to store it inside the JSON object. 
 
-If the `datacontenttype` value is either ["application/json"][rfc4627] or any
-media type with a [structured +json suffix][rfc6839], the implementation MUST
-translate the `data` value into a [JSON value][json-value], and set
-the `data` attribute of the envelope JSON object to this JSON value.
+For any other type, the implementation MUST translate the `data` value into 
+a [JSON value][json-value], and use the member name `data`
+to store it inside the JSON object. 
 
-If the `datacontenttype` value does not follow the [structured +json
-suffix][rfc6839] but is known to use JSON encoding, the implementation MUST
-translate the `data` value into a [JSON value][json-value], and set
-the `data` attribute of the envelope JSON object to this JSON value. Its typical
-examples are, but not limited to, `text/json`,
-[`application/json-seq`][json-seq] and
-[`application/geo+json-seq`][json-geoseq].
+Out of this follows that use of the `data` and `data_base64` members is
+mutually exclusive in a JSON serialized CloudEvent. 
 
-Unlike all other attributes, for which value types are restricted to strings per
-the [type-system mapping](#22-type-system-mapping), the resulting `data` member
-[JSON value][json-value] is unrestricted, and MAY also contain numeric and
-logical JSON types.
+When a CloudEvents is deserialized from JSON, the presence of the `data_base64`
+member clearly indicates that the value is a Base64 encoded binary data, which
+the serializer MUST decode into a binary runtime data type. When a `data` 
+member is present, it is decoded using the default JSON type mapping for the 
+used runtime.  
 
-Second, whether a Base64-encoded string in `data` is treated as
-`Binary` or as a `String` is also determined by the `datacontenttype` value. If
-the `datacontenttype` media type is known to contain text, the data attribute
-value is not further interpreted and treated as a text string. Otherwise, it is
-decoded and treated as a binary value.
+Unlike attributes, for which value types are restricted to strings per
+the [type-system mapping](#22-type-system-mapping), the resulting `data` member
+[JSON value][json-value] is unrestricted, and MAY contain any valid JSON.
 
 ### 3.2. Examples
 
@@ -195,12 +179,12 @@ Example event with `Binary`-valued data
         "otherValue": 5
     },
     "datacontenttype" : "application/vnd.apache.thrift.binary",
-    "data" : "... base64 encoded string ..."
+    "data_base64" : "... base64 encoded string ..."
 }
 ```
 
 Example event with JSON data for the "data" member, either derived from a `Map`
-or [JSON data](#31-special-handling-of-data) data:
+or [JSON data](#31-handling-of-data) data:
 
 ```JSON
 {
@@ -264,7 +248,7 @@ second with JSON data.
           "otherValue": 5
       },
       "datacontenttype" : "application/vnd.apache.thrift.binary",
-      "data" : "... base64 encoded string ..."
+      "data_base64" : "... base64 encoded string ..."
   },
   {
       "specversion" : "0.4-wip",

diff --git a/spec.json b/spec.json
@@ -11,6 +11,9 @@
     "data": {
       "type": ["object", "string"]
     },
+    "data_base64": {
+      "type": "string"
+    },
     "event": {
       "properties": {
         "specversion": {
@@ -22,6 +25,9 @@
         "data": {
           "$ref": "#/definitions/data"
         },
+        "data_base64": {
+          "$ref": "#/definitions/data_base64"
+        },
         "id": {
           "$ref": "#/definitions/id"
         },

diff --git a/spec.md b/spec.md
@@ -311,27 +311,6 @@ The following attributes are OPTIONAL to appear in CloudEvents. See the
 [Notational Conventions](#notational-conventions) section for more information
 on the definition of OPTIONAL.
 
-#### datacontentencoding
-
-- Type: `String` per
-  [RFC 2045 Section 6.1](https://tools.ietf.org/html/rfc2045#section-6.1)
-- Description: Describes the content encoding for `data`.
-  There are cases where the value of `data` might need to be
-  encoded so that it can be carried within the serialization format being used.
-  For example, in JSON, binary data will likely need to be Base64 encoded.
-  When this attribute is set, the consumer can use its value to know how
-  to decode `data` value to retrieve its original contents.
-
-  If this attribute is supported, then the "Base64" encoding as defined in
-  [RFC 2045 Section 6.8](https://tools.ietf.org/html/rfc2045#section-6.8) MUST
-  be supported.
-
-- Constraints:
-  - The attribute MUST be set if `data` is encoded and not
-    in its original format. Otherwise the attribute MUST NOT be set.
-  - If present, MUST adhere to
-    [RFC 2045 Section 6.1](https://tools.ietf.org/html/rfc2045#section-6.1)
-
 #### datacontenttype
 
 - Type: `String` per [RFC 2046](https://tools.ietf.org/html/rfc2046)
@@ -344,7 +323,7 @@ on the definition of OPTIONAL.
   `data` content is rendered for different `datacontenttype`
   values are defined in the event format specifications; for example, the JSON
   event format defines the relationship in
-  [section 3.1](./json-format.md#31-special-handling-of-data).
+  [section 3.1](./json-format.md#31-handling-of-data).
 
   When this attribute is omitted, `data` simply follows the event
   format's encoding rules. For the JSON event format, the `data` value
@@ -464,13 +443,8 @@ encapsulated within `data`.
   restriction on the type of this information. It is encoded into a media format
   which is specified by the `datacontenttype` attribute (e.g.
   application/json), and adheres to the `dataschema` format when those
-  repspective attributes are present.
+  respective attributes are present.
 
-  If `data`'s native syntax, or its syntax based on the `datacontenttype`
-  attribute if present, can not be copied directly into the desired
-  serialization format, and therefore needs to be further encoded, then
-  the `datacontentencoding` attribute MUST include the encoding mechanism
-  used.
 - Constraints:
   - OPTIONAL