Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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
12 changes: 12 additions & 0 deletions amqp-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,18 @@ exceptions noted below.
| Map | [map][amqp-map] |
| Any | See 2.3. |

A CloudEvents AMQP format implementation MUST allow for attribute values to be
convertible from/to their canonical CloudEvents string representation. For
instance, the `time` attribute MUST be convertible from and to a conformant
RFC3339 string value.

If an non-string attribute is received as string from a communicating party,
an AMQP intermediary MAY convert it to the native AMQP representation before
forwarding the event; an AMQP consumer SHOULD convert it to the native AMQP
representation before surfacing the value to the API. An AMQP implementation
SHOULD convert from/to the native runtime or language type system to the AMQP
type system directly without translating through strings whenever possible.

Extension specifications MAY define diverging mapping rules for the values of
attributes they define.

Expand Down
10 changes: 5 additions & 5 deletions amqp-transport-binding.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,11 +201,11 @@ content-type: application/json; charset=utf-8

----------- application-properties -----------

cloudEvents:specversion: "0.3-wip"
cloudEvents:type: "com.example.someevent"
cloudEvents:time: "2018-04-05T03:56:24Z"
cloudEvents:id: "1234-1234-1234"
cloudEvents:source: "/mycontext/subcontext"
cloudEvents:specversion: 0.3-wip
cloudEvents:type: com.example.someevent
cloudEvents:time: 2018-04-05T03:56:24Z
cloudEvents:id: 1234-1234-1234
cloudEvents:source: /mycontext/subcontext
.... further attributes ...

------------- application-data ---------------
Expand Down
31 changes: 14 additions & 17 deletions http-transport-binding.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,18 +206,17 @@ specification, header names are case-insensitive.

##### 3.1.3.2 HTTP Header Values

The value for each HTTP header is constructed from the respective attribute's
[JSON value][json-value] representation, compliant with the [JSON event
format][json-format] specification.
The value for each HTTP header is constructed from the respective attribute
type's canonical string representation.

Some CloudEvents metadata attributes can contain arbitrary UTF-8 string content,
and per [RFC7230 Section 3][rfc7230-section-3], HTTP headers MUST only use
printable characters from the US-ASCII character set, and are terminated by a
CRLF sequence.

Therefore, and analog to the encoding rules for Universal character set host
names in URIs [RFC3986 3.2.2][rfc3986], the JSON value MUST be encoded as
follows:
names in URIs [RFC3986 3.2.2][rfc3986], the string value MUST be further encoded
as follows:

Non-printable ASCII characters and non-ASCII characters MUST first be encoded
according to UTF-8, and then each octet of the corresponding UTF-8 sequence MUST
Expand All @@ -226,8 +225,6 @@ with [RFC7230, sections 3, 3.2, 3.2.6][rfc7230-section-3]. The rules for
encoding of the percent character ('%') apply as defined in [RFC 3986 Section
2.4.][rfc3986-section-2-4].

JSON objects and arrays are NOT surrounded with single or double quotes.

#### 3.1.4 Examples

This example shows the _binary_ mode mapping of an event with an HTTP POST
Expand All @@ -236,11 +233,11 @@ request:
```text
POST /someresource HTTP/1.1
Host: webhook.example.com
ce-specversion: "0.3-wip"
ce-type: "com.example.someevent"
ce-time: "2018-04-05T03:56:24Z"
ce-id: "1234-1234-1234"
ce-source: "/mycontext/subcontext"
ce-specversion: 0.3-wip
ce-type: com.example.someevent
ce-time: 2018-04-05T03:56:24Z
ce-id: 1234-1234-1234
ce-source: /mycontext/subcontext
.... further attributes ...
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
Expand All @@ -254,11 +251,11 @@ This example shows a response containing an event:

```text
HTTP/1.1 200 OK
ce-specversion: "0.3-wip"
ce-type: "com.example.someevent"
ce-time: "2018-04-05T03:56:24Z"
ce-id: "1234-1234-1234"
ce-source: "/mycontext/subcontext"
ce-specversion: 0.3-wip
ce-type: com.example.someevent
ce-time: 2018-04-05T03:56:24Z
ce-id: 1234-1234-1234
ce-source: /mycontext/subcontext
.... further attributes ...
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
Expand Down
13 changes: 6 additions & 7 deletions mqtt-transport-binding.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,8 +176,7 @@ in the MQTT PUBLISH message.
##### 3.1.3.2 User Property Values

The value for each MQTT PUBLISH User Property MUST be constructed from the
respective CloudEvents attribute's JSON type representation, compliant with the
[JSON event format][json-format] specification.
respective CloudEvents attribute type's canonical string representation.

#### 3.1.4 Examples

Expand All @@ -198,11 +197,11 @@ Content Type: application/json; charset=utf-8

------------- User Properties ----------------

specversion: "0.3-wip"
type: "com.example.someevent"
time: "2018-04-05T03:56:24Z"
id: "1234-1234-1234"
source: "/mycontext/subcontext"
specversion: 0.3-wip
type: com.example.someevent
time: 2018-04-05T03:56:24Z
id: 1234-1234-1234
source: /mycontext/subcontext
.... further attributes ...

------------------ payload -------------------
Expand Down
37 changes: 32 additions & 5 deletions spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,20 +148,47 @@ specific protocols (AWS Kinesis, Azure Event Grid).

## Type System

The following abstract data types are available for use in attributes.
The following abstract data types are available for use in attributes. Each of
these types MAY be represented differently by different event formats and in
transport metadata fields. This specification defines a canonical string-encoding
for each type that MUST be supported by all implementations.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Even if that impl only supports transports/formats that don't use the string encoding?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@duglin Yes, all implementations need to expect a string value to come across the wire where the "native" representation would be a binary-encoded number, for instance. Interop.


A strongly-typed programming model that represents a CloudEvent or any
extension MUST be able to convert from and to the canonical string-encoding to
the runtime/language native type that best corresponds to the abstract type.

For example, the `time` attribute might be represented by the language's native
*datetime* type in a given implementation, but it MUST be settable providing
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

"MUST be settable"... not sure what this means. Does this mean the SDK's setter MUST accept a "string" value from the user? Or is this more about how there are certain transports that will use the string-encoding and impls that support that transport must be prepared to convert between strings and the native type?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Oh, the next sentence covers the transport stuff. So I think I'm back to not understanding what the "settable" part means in practice.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@duglin "settable" means that the implementation MUST ALWAYS allow the app to set a time value via its string representation, either from the SDK side (e.g. you're building a forwarder that maps between transports) or from the wire side, even if the "native" representation of the type isn't string. E.g. set_time(time_t) and set_time(string).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

ok that helps clarify things- thanks.

However, is this out of scope for the spec? Should this be guidance in the sdk doc? I'm not sure the spec, which is just about (mainly) defining the metadata, should get into how the metadata is set/retrieved by the app/user. Especially via a "MUST" - as non-normative guidance I can see though.

an RFC3339 string, and it MUST be convertible to an RFC3339 string when mapped
to a header of an HTTP message.

A CloudEvents transport binding or event format implementation MUST likewise
be able to convert from and to the canonical string-encoding to the
corresponding data type in the encoding or in transport metadata fields.

An attribute value of type `Timestamp` might indeed be routed as a string
through multiple hops and only materialize as a native runtime/language type
at the producer and ultimate consumer. The `Timestamp` might also
be routed as a native transport type and might be mapped to/from the respective
language/runtime types at the producer and consumer ends, and never materialize
as a string.

- `Integer` - A whole number in the range -2,147,483,648 to +2,147,483,647
inclusive. This is the range of a signed, 32-bit, twos-complement encoding.
Event formats do not have to use this encoding, but they MUST only use
`Integer` values in this range.
- String encoding: Integer portion of the JSON Number per [RFC 7159, Section 6](https://tools.ietf.org/html/rfc7159#section-6)
- `String` - Sequence of printable Unicode characters.
- `Binary` - Sequence of bytes.
- String encoding: Base64 encoding per [RFC4648](https://tools.ietf.org/html/rfc4648).
- `Map` - `String`-indexed dictionary of `Any`-typed values.
- String encoding: JSON Object per [RFC 7159, Section 4](https://tools.ietf.org/html/rfc7159#section-4)
- `Any` - Either a `Binary`, `Integer`, `Map` or `String`.
- `URI-reference` - String expression conforming to `URI-reference` as defined
in [RFC 3986 §4.1](https://tools.ietf.org/html/rfc3986#section-4.1).
- `Timestamp` - String expression as defined in
[RFC 3339](https://tools.ietf.org/html/rfc3339).
- `URI-reference` - Uniform resource identifier reference.
- String encoding: `URI-reference` as defined
in [RFC 3986 Section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1).
- `Timestamp` - Date and time expression using the Gregorian Calendar.
- String encoding: [RFC 3339](https://tools.ietf.org/html/rfc3339).

The `Any` type is a variant type that can take the shape of either a `Binary`,
`Integer`, `Map` or `String`. The type system is intentionally abstract, and
Expand Down