Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

remove dataencoding and intro data_base64 in JSON #492

Merged
merged 5 commits into from
Sep 5, 2019
Merged

remove dataencoding and intro data_base64 in JSON #492

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
92d3e40
Changed datacontentencoding to dataencoding
Aug 27, 2019
acb8e53
remove dataencoding and intro data_base64 in JSON
Aug 29, 2019
8393f8d
Consolidated handling of "data" in the JSON spec
Sep 4, 2019
771e329
Link fix
Sep 4, 2019
7cdb978
link fix
Sep 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion adapters/aws-s3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
11 changes: 0 additions & 11 deletions adapters/gitlab.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
Expand Down
68 changes: 26 additions & 42 deletions json-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| --------------- | ------------- | ------------------------------- |
Expand All @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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
{
Expand Down Expand Up @@ -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",
Expand Down
6 changes: 6 additions & 0 deletions spec.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@
"data": {
"type": ["object", "string"]
},
"data_base64": {
"type": "string"
},
"event": {
"properties": {
"specversion": {
Expand All @@ -22,6 +25,9 @@
"data": {
"$ref": "#/definitions/data"
},
"data_base64": {
"$ref": "#/definitions/data_base64"
},
"id": {
"$ref": "#/definitions/id"
},
Expand Down
30 changes: 2 additions & 28 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -309,27 +309,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)
Expand All @@ -342,7 +321,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
Expand Down Expand Up @@ -462,13 +441,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

Expand Down