Skip to content

Commit

Permalink
Added data payload
Browse files Browse the repository at this point in the history 
Fixes cloudevents#261

This change causes data to not be thought of as an attribute, rather to
be considered an opaque blob described by the content type. The name
given is data payload. The wording in the JSON encoding has been
modified to reflect this.
  • Loading branch information
@jroper
jroper committed Jun 18, 2019
1 parent dc01c1b commit e226432
Show file tree
Hide file tree
Showing 7 changed files with 143 additions and 151 deletions.
28 changes: 14 additions & 14 deletions amqp-transport-binding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ This document is a working draft.
2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes)

- 2.1. [datacontenttype Attribute](#21-datacontenttype-attribute)
- 2.2. [data Attribute](#22-data-attribute)
- 2.2. [Data Payload](#22-data-payload)

3. [AMQP Message Mapping](#3-amqp-message-mapping)

Expand Down Expand Up @@ -108,18 +108,18 @@ event metadata. Any mention of event attributes other than `datacontenttype` and
The `datacontenttype` attribute is assumed to contain a [RFC2046][rfc2046]
compliant media-type expression.

### 2.2. data Attribute
### 2.2. Data Payload

The `data` attribute is assumed to contain opaque application data that is
The data payload is assumed to contain opaque application data that is
encoded as declared by the `datacontenttype` attribute.

An application is free to hold the information in any in-memory representation
of its choosing, but as the value is transposed into AMQP as defined in this
specification, the assumption is that the `data` attribute value is made
specification, the assumption is that the data payload value is made
available as a sequence of bytes.

For instance, if the declared `datacontenttype` is
`application/json;charset=utf-8`, the expectation is that the `data` attribute
`application/json;charset=utf-8`, the expectation is that the data payload
value is made available as [UTF-8][rfc3629] encoded JSON text for use in AMQP.

## 3. AMQP Message Mapping
Expand All @@ -141,7 +141,7 @@ treat the event as binary and forward it to another party as-is.

### 3.1. Binary Content Mode

The _binary_ content mode accommodates any shape of event data, and allows for
The _binary_ content mode accommodates any shape of data payload, and allows for
efficient transfer and without transcoding effort.

#### 3.1.1. AMQP content-type
Expand All @@ -151,13 +151,13 @@ directly to the CloudEvents `datacontenttype` attribute.

#### 3.1.2. Event Data Encoding

The [`data` attribute](#22-data-attribute) byte-sequence is used as the AMQP
The [data payload](#22-data-payload) byte-sequence is used as the AMQP
[application-data][data] section.

#### 3.1.3. Metadata Headers

All [CloudEvents][ce] attributes with exception of `datacontenttype` and `data`
MUST be individually mapped to and from the AMQP
All [CloudEvents][ce] attributes with exception of `datacontenttype` 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
Expand Down Expand Up @@ -236,12 +236,12 @@ content-type: application/cloudevents+json; charset=UTF-8

#### 3.2.2. Event Data Encoding

The chosen [event format](#14-event-formats) defines how all attributes,
including the `data` attribute, are represented.
The chosen [event format](#14-event-formats) defines how all attributes and the
data payload are represented.

The event metadata and data is then rendered in accordance with the event format
specification and the resulting data becomes the AMQP application [data][data]
section.
The event metadata and payload is then rendered in accordance with the event
format specification and the resulting data becomes the AMQP application
[data][data] section.

#### 3.2.3. Metadata Headers

Expand Down
53 changes: 27 additions & 26 deletions http-transport-binding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ This document is a working draft.
2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes)

- 2.1. [datacontenttype Attribute](#21-datacontenttype-attribute)
- 2.2. [data Attribute](#22-data-attribute)
- 2.2. [Data Payload](#22-data-payload)

3. [HTTP Message Mapping](#3-http-message-mapping)

Expand Down Expand Up @@ -69,13 +69,13 @@ This specification defines three content modes for transferring events:
_binary_, _structured_ and _batched_. Every compliant implementation SHOULD
support the _structured_ and _binary_ modes.

In the _binary_ content mode, the value of the event `data` attribute is placed
In the _binary_ content mode, the value of the event data payload is placed
into the HTTP request or response body as-is, with the `datacontenttype`
attribute value declaring its media type; all other event attributes are mapped
to HTTP headers.

In the _structured_ content mode, event metadata attributes and event data are
placed into the HTTP request or response body using an
In the _structured_ content mode, event metadata attributes and data payload
are placed into the HTTP request or response body using an
[event format](#14-event-formats).

In the _batched_ content mode several events are batched into a single HTTP
Expand Down Expand Up @@ -103,33 +103,33 @@ identically to [HTTP over TLS]([RFC2818][RFC2818]).
This specification does not further define any of the [CloudEvents][ce] event
attributes.

Two of the event attributes, `datacontenttype` and `data` are handled specially
and mapped onto HTTP constructs, all other attributes are transferred as
metadata without further interpretation.
The `datacontenttype` attribute is handled specially and mapped onto HTTP
constructs, all other attributes are transferred as metadata without further
interpretation.

This mapping is intentionally robust against changes, including the addition and
removal of event attributes, and also accommodates vendor extensions to the
event metadata. Any mention of event attributes other than `datacontenttype` and
`data` is exemplary.
event metadata. Any mention of event attributes other than `datacontenttype` is
exemplary.

### 2.1. datacontenttype Attribute

The `datacontenttype` attribute is assumed to contain a [RFC2046][rfc2046]
compliant media-type expression.

### 2.2. data Attribute
### 2.2. Data Payload

The `data` attribute is assumed to contain opaque application data that is
The data payload is assumed to contain opaque application data that is
encoded as declared by the `datacontenttype` attribute.

An application is free to hold the information in any in-memory representation
of its choosing, but as the value is transposed into HTTP as defined in this
specification, the assumption is that the `data` attribute value is made
available as a sequence of bytes.
specification, the assumption is that the data payload is made available as a
sequence of bytes.

For instance, if the declared `datacontenttype` is
`application/json;charset=utf-8`, the expectation is that the `data` attribute
value is made available as [UTF-8][rfc3629] encoded JSON text to HTTP.
`application/json;charset=utf-8`, the expectation is that the data payload is
made available as [UTF-8][rfc3629] encoded JSON text to HTTP.

## 3. HTTP Message Mapping

Expand All @@ -154,8 +154,8 @@ treat the event as binary and forward it to another party as-is.

### 3.1. Binary Content Mode

The _binary_ content mode accommodates any shape of event data, and allows for
efficient transfer and without transcoding effort.
The _binary_ content mode accommodates any shape of data payload, and allows
for efficient transfer and without transcoding effort.

#### 3.1.1. HTTP Content-Type

Expand All @@ -164,14 +164,14 @@ CloudEvents `datacontenttype` attribute.

#### 3.1.2. Event Data Encoding

The [`data` attribute](#22-data-attribute) byte-sequence is used as the HTTP
The [data payload](#22-data-payload) byte-sequence is used as the HTTP
message body.

#### 3.1.3. Metadata Headers

All [CloudEvents][ce] attributes with exception of `datacontenttype` and `data`
MUST be individually mapped to and from distinct HTTP message headers, with
exceptions noted below.
All [CloudEvents][ce] attributes with exception of `datacontenttype` 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
Expand Down Expand Up @@ -284,11 +284,12 @@ Content-Type: application/cloudevents+json; charset=UTF-8

#### 3.2.2. Event Data Encoding

The chosen [event format](#14-event-formats) defines how all attributes,
including the `data` attribute, are represented.
The chosen [event format](#14-event-formats) defines how all attributes and the
data payload are represented.

The event metadata and data is then rendered in accordance with the event format
specification and the resulting data becomes the HTTP message body.
The event metadata and data payload is then rendered in accordance with the
event format specification and the resulting data becomes the HTTP message
body.

#### 3.2.3. Metadata Headers

Expand Down Expand Up @@ -365,7 +366,7 @@ Content-Type: application/cloudevents-batch+json; charset=UTF-8
#### 3.3.2. Event Data Encoding

The chosen [event format](#14-event-formats) defines how a batch of events and
all event attributes, including the `data` attribute, are represented.
all event attributes and the data payload are represented.

The batch of events is then rendered in accordance with the event format
specification and the resulting data becomes the HTTP message body.
Expand Down
63 changes: 28 additions & 35 deletions json-format.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,8 @@ respective CloudEvents type when the mapping rules are fulfilled.

### 2.3. Mapping Any-typed Attributes

The CloudEvents `data` attribute is `Any`-typed, meaning that it holds a value
of any valid type. `Map` entry values are also `Any` typed.
CloudEvents attributes may be `Any`-typed, meaning that they hold a value of
any valid type. `Map` entry values are also `Any` typed.

If an implementation determines that the actual type of an `Any` is a `String`,
the value MUST be represented as [JSON string][json-string] expression; for
Expand All @@ -114,9 +114,6 @@ 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

Expand All @@ -125,7 +122,8 @@ The CloudEvents [JSONSchema](http://json-schema.org) for the spec is located

## 3. Envelope

Each CloudEvents event can be wholly represented as a JSON object.
Each CloudEvents event can be wholly represented as a
[JSON object][json-object].

Such a representation MUST use the media type `application/cloudevents+json`.

Expand All @@ -134,42 +132,38 @@ 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 the "data" Attribute
The data payload, if present, MUST be mapped to a member named `data`,
according to the [Data Payload](#31-data-payload) section. If no data payload
is present, the envelope MUST NOT contain a `data` member.

The mapping of the `Any`-typed `data` attribute follows the rules laid out in
[Section 2.3.](#23-mapping-any-typed-attributes), with two additional rules:
### 3.1. Data Payload

First, if an implementation determines that the type of the `data` attribute is
`Binary` or `String`, it MUST inspect the `datacontenttype` attribute to
determine whether it is indicated that the data value contains JSON data.
The mapping of the data payload to a [JSON value][json-value] depends on the
`datacontenttype` attribute.

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` attribute value into a [JSON value][json-value], and set
the `data` attribute of the envelope JSON object to this JSON value.

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` attribute 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`,
If the `datacontenttype` is [`"application/json"`][rfc4627], any structured
media type with a [structured `+json` suffix][rfc6839], any other media type
that is known by the implementation to use JSON encoding, or if through some
other means the implementation knows that the payload is JSON, the data payload
MUST be encoded as a [JSON value][json-value], and set as the value for the
`data` member. Typical examples of media types that are known to use JSON
encoding are, but not limited to, `text/json`,
[`application/json-seq`][json-seq] and
[`application/geo+json-seq`][json-geoseq].

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.
If the `datacontenttype` is any media type that is any text media type, that is
any media type that is prefixed with `text/`, excluding media types that are
known to use JSON encoding, then the data payload MUST be encoded as a
[JSON string][json-string], and set as the value for the `data` member.

Second, whether a Base64-encoded string in the data attribute 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.
If the `datacontenttype` is anything else, or is not set and the implementation
does not know it to be JSON, then the payload bytes must be [Base64][base64]
encoded, then encoded as a [JSON String][json-string], and set as the value for
the `data` member.

### 3.2. Examples

Example event with `String`-valued `data`:
Example event with a data payload that has a `text/*` media type:

```JSON
{
Expand All @@ -187,7 +181,7 @@ Example event with `String`-valued `data`:
}
```

Example event with `Binary`-valued data
Example event with a non JSON, non text media type:

```JSON
{
Expand All @@ -205,8 +199,7 @@ Example event with `Binary`-valued data
}
```

Example event with JSON data for the "data" member, either derived from a `Map`
or [JSON data](#31-special-handling-of-the-data-attribute) data:
Example event with JSON data for the `data` member:

```JSON
{
Expand Down
Loading

0 comments on commit e226432

Please sign in to comment.