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.

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
Show file tree
Hide file tree
Changes from 2 commits
Commits
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
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
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
19 changes: 8 additions & 11 deletions json-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,9 +92,12 @@ respective CloudEvents type when the mapping rules are fulfilled.
### 2.3. Mapping Data
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Terrible nit, but I think this should be in section 3 now, because we've removed data from the attributes, and section 2 is "Attributes".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would also put this text closer to the text in section 3.1 'Special Handling of "data"'.


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.
the value MUST be represented as [JSON string][json-string] expression and the
member name inside the JSON object MUST be `data`. For `Binary`, the value MUST
be represented as a [JSON string][json-string] expression containing the
[Base64][base64] encoded binary value, and the member name inside the JSON
object MUST be `data_base64`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While it's implied, it doesn't actually ban someone from having both data and data_base64 in the JSON. Can we add something like:

Note, `data` and `data_base64` MUST NOT both appear at the same time within a CloudEvent serialization.

Someone may try to be "smart" and fill in both (when possible, like when it's a string) and that's a situation I think we need to avoid.

Also, could someone misinterpret the Binary usage here? I believe you mean that the data type of data is binary and you're not referring to the binary serialization of the CE. Perhaps:


For cases where data is a Binary value, it MUST be represented ....




### 2.4. Examples

Expand Down Expand Up @@ -155,12 +158,6 @@ 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.

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.

### 3.2. Examples

Example event with `String`-valued `data`:
Expand Down Expand Up @@ -195,7 +192,7 @@ Example event with `Binary`-valued data
"otherValue": 5
},
"datacontenttype" : "application/vnd.apache.thrift.binary",
"data" : "... base64 encoded string ..."
"data_base64" : "... base64 encoded string ..."
}
```

Expand Down Expand Up @@ -264,7 +261,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
28 changes: 1 addition & 27 deletions spec.md
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 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