diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 0205efc96..fd0f94897 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -77,7 +77,7 @@ If a vote is taken during a meeting, the follow rules will be followed: An acceptable absence would include situations where the person is not officially working at all, such as being on vacation, taking a sabbatical or there is a public holiday. However, situations such as a scheduling conflict - would not apply. Absence from meetings during that time will not impact + would not apply. Absence from meetings during that time will not impact their voting rights. - Only members with voting rights will be allowed to vote. - A vote passes if more than 50% of the votes cast approve the motion. @@ -122,8 +122,8 @@ To create a new release: - Add some descriptive text, or the list of PRs that have been merged since the previous release. The git query to get the list commits since the last release is: - `git log --pretty=format:%s master...v0.1 | grep -v "Merge pull"`. - Just replace "v0.1" with the name of the previous release. + `git log --pretty=format:%s master...v0.1 | grep -v "Merge pull"`. + Just replace "v0.1" with the name of the previous release. - Press `Publish release` button - Create a PR that modifies the version string in all of the files (but not the README.md table) to be the next version number with a `-wip` diff --git a/README.md b/README.md index 8c26459fa..797ada3c7 100644 --- a/README.md +++ b/README.md @@ -24,27 +24,27 @@ a Cloud Native sandbox level project on The following documents are available: -| | Latest Release | Working Draft | -| :---------------------------- | :-----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | +| | Latest Release | Working Draft | +| :---------------------------- | :-------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | | **Core Specification:** | | CloudEvents | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | | | | **Optional Specifications:** | -| AMQP Transport Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/amqp-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | -| AVRO Event Format | - | [master](./avro-format.md) | -| HTTP Protocol Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/http-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | +| AMQP Transport Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/amqp-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | +| AVRO Event Format | - | [master](./avro-format.md) | +| HTTP Protocol Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/http-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | | JSON Event Format | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) | -| Kafka Protocol Binding | - | [master](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md) | -| MQTT Protocol Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/mqtt-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-protocol-binding.md) | -| NATS Protocol Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/nats-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | +| Kafka Protocol Binding | - | [master](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md) | +| MQTT Protocol Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/mqtt-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-protocol-binding.md) | +| NATS Protocol Binding | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/nats-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | | Web hook | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | | | | **Additional Documentation:** | -| CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | -| CloudEvents SDK Requirements | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/SDK.md) | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | -| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | +| CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | +| CloudEvents SDK Requirements | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/SDK.md) | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | +| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | | Primer | [v1.0-rc1](https://github.com/cloudevents/spec/blob/v1.0-rc1/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | -| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | +| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | If you are new to CloudEvents, it is recommended that you start by reading the [Primer](primer.md) for an overview of the specification's goals and design diff --git a/adapters.md b/adapters.md index faca1ad14..499f3b299 100644 --- a/adapters.md +++ b/adapters.md @@ -7,6 +7,6 @@ CloudEvents attributes. In order to promote interoperability across multiple implementations of these adpaters, the following documents show the proposed algorithms that should be used: -* [AWS S3](adapters/aws-s3.md) -* [GitHub](adapters/github.md) -* [GitLab](adapters/gitlab.md) +- [AWS S3](adapters/aws-s3.md) +- [GitHub](adapters/github.md) +- [GitLab](adapters/gitlab.md) diff --git a/amqp-protocol-binding.md b/amqp-protocol-binding.md index eb7a6711f..c63c6ce11 100644 --- a/amqp-protocol-binding.md +++ b/amqp-protocol-binding.md @@ -89,7 +89,7 @@ mandate specific existing features to be used. This specification does not further define any of the [CloudEvents][ce] event attributes. -One event attribute, `datacontenttype` is handled specially in *binary* content +One event attribute, `datacontenttype` is handled specially in _binary_ content mode and mapped onto the AMQP content-type message property. All other attributes are transferred as metadata without further interpretation. @@ -194,12 +194,12 @@ the native AMQP types above or the canonical string form. An implementation -- MUST be able to interpret both forms on an incoming AMQP message +- MUST be able to interpret both forms on an incoming AMQP message - MAY further relax the requirements for incoming messages (for example -accepting numeric types other than AMQP long), but MUST be strict for outgoing -messages. + accepting numeric types other than AMQP long), but MUST be strict for outgoing + messages. - SHOULD use the native AMQP form on outgoing AMQP messages when it is efficient -to do so, but MAY forward values as canonical strings + to do so, but MAY forward values as canonical strings #### 3.1.4 Examples @@ -312,11 +312,7 @@ content-type: application/cloudevents+json; charset=utf-8 [rfc4627]: https://tools.ietf.org/html/rfc4627 [rfc6839]: https://tools.ietf.org/html/rfc6839#section-3.1 [rfc7159]: https://tools.ietf.org/html/rfc7159 -[oasis-amqp-1.0]: - http://docs.oasis-open.org/amqp/core/v1.0/amqp-core-overview-v1.0.html -[message-format]: - http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format -[data]: - http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-data -[app-properties]: - http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-application-properties +[oasis-amqp-1.0]: http://docs.oasis-open.org/amqp/core/v1.0/amqp-core-overview-v1.0.html +[message-format]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format +[data]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-data +[app-properties]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-application-properties diff --git a/documented-extensions.md b/documented-extensions.md index 4772ac36e..9acfaaf98 100644 --- a/documented-extensions.md +++ b/documented-extensions.md @@ -32,7 +32,7 @@ MAY), this usage only applies to events that use the extension. Extensions attributes, while not defined by the core CloudEvents specifications, MUST follow the same serialization rules as defined by the format and protocol -binding specifications. See +binding specifications. See [Extension Context Attributes](spec.md#extension-context-attributes) for more information. diff --git a/extensions/dataref.md b/extensions/dataref.md index 41fb1bf9b..886c9306d 100644 --- a/extensions/dataref.md +++ b/extensions/dataref.md @@ -15,37 +15,38 @@ attribute by using the `dataref` attribute. ## Attributes ### dataref -* Type: `URI-reference` -* Description: A reference to a location where the event payload is stored. The + +- Type: `URI-reference` +- Description: A reference to a location where the event payload is stored. The location MAY not be accessible without further information (e.g. a pre-shared secret). Known as the "Claim Check Pattern", this attribute MAY be used for a variety of purposes, including: - * If the [Data](../spec.md#data) is too large to be included in the message, + - If the [Data](../spec.md#data) is too large to be included in the message, the `data` is not present, and the consumer can retrieve it using this attribute. - * If the consumer wants to verify that the [Data](../spec.md#data) has not + - If the consumer wants to verify that the [Data](../spec.md#data) has not been tampered with, it can retrieve it from a trusted source using this attribute. - * If the [Data](../spec.md#data) MUST only be viewed by trusted consumers - (e.g. personally identifiable information), only a trusted consumer can + - If the [Data](../spec.md#data) MUST only be viewed by trusted consumers + (e.g. personally identifiable information), only a trusted consumer can retrieve it using this attribute and a pre-shared secret. If this attribute is used, the information SHOULD be accessible long enough for all consumers to retrieve it, but MAY not be stored for an extended period of time. -* Constraints: - * OPTIONAL +- Constraints: + - OPTIONAL # Examples The following example shows a CloudEvent in which the event producer has included both `data` and `dataref` (serialized as JSON): -``` JSON +```JSON { "specversion" : "1.0-rc1", "type" : "com.github.pull.create", @@ -60,7 +61,7 @@ both `data` and `dataref` (serialized as JSON): The following example shows a CloudEvent in which a middleware has replaced the `data` with a `dataref` (serialized as JSON): -``` JSON +```JSON { "specversion" : "1.0-rc1", "type" : "com.github.pull.create", @@ -70,4 +71,3 @@ The following example shows a CloudEvent in which a middleware has replaced the "dataref" : "https://tenant123.middleware.com/events/data/A234-1234-1234.xml" } ``` - diff --git a/extensions/partitioning.md b/extensions/partitioning.md index c7c866f4a..38443f6eb 100644 --- a/extensions/partitioning.md +++ b/extensions/partitioning.md @@ -14,15 +14,15 @@ same bucket are done so by using the same partition key on those events. ### partitionkey -* Type: `String` -* Description: A partition key for the event, typically for the purposes of +- Type: `String` +- Description: A partition key for the event, typically for the purposes of defining a causal relationship/grouping between multiple events. In cases where the CloudEvent is delivered to an event consumer via multiple hops, - it is possible that the value of this attribute might change, or even be - removed, due to protocol semantics or business processing logic within + it is possible that the value of this attribute might change, or even be + removed, due to protocol semantics or business processing logic within each hop. -* Examples: - * The ID of the entity that the event is associated with -* Constraints: - * REQUIRED - * MUST be a non-empty string +- Examples: + - The ID of the entity that the event is associated with +- Constraints: + - REQUIRED + - MUST be a non-empty string diff --git a/extensions/sampled-rate.md b/extensions/sampled-rate.md index 6af980057..bf8394585 100644 --- a/extensions/sampled-rate.md +++ b/extensions/sampled-rate.md @@ -26,4 +26,4 @@ they impose additional sampling. would be 30 (29 not sent and 1 sent). A value of `1` is the equivalent of this extension not being used at all. - Constraints - - The rate MUST be greater than zero. \ No newline at end of file + - The rate MUST be greater than zero. diff --git a/http-webhook.md b/http-webhook.md index 9d796bc0d..f17d1eab6 100644 --- a/http-webhook.md +++ b/http-webhook.md @@ -188,7 +188,7 @@ it. Reaching the delivery agreement is realized using the following validation handshake. The handshake can either be executed immediately at registration time -or as a "pre-flight" request immediately preceding a delivery. +or as a "pre-flight" request immediately preceding a delivery. It is important to understand is that the handshake does not aim to establish an authentication or authorization context. It only serves to protect the sender @@ -346,8 +346,7 @@ WebHook-Allowed-Rate: 100 - [RFC7540][rfc7540] Hypertext Transfer Protocol Version 2 (HTTP/2) [ce]: ./spec.md -[webhooks]: - http://progrium.com/blog/2007/05/03/web-hooks-to-revolutionize-the-web/ +[webhooks]: http://progrium.com/blog/2007/05/03/web-hooks-to-revolutionize-the-web/ [content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 [retry-after]: https://tools.ietf.org/html/rfc7231#section-7.1.3 [authorization]: https://tools.ietf.org/html/rfc7235#section-4.2 diff --git a/json-format.md b/json-format.md index b3d34e4b4..8c4a5f786 100644 --- a/json-format.md +++ b/json-format.md @@ -62,7 +62,7 @@ with exceptions noted below. | CloudEvents | JSON | | ------------- | -------------------------------------------------------------- | -| Boolean | [boolean][json-bool] +| Boolean | [boolean][json-bool] | | Integer | [number][json-number], only the `int` component is permitted | | String | [string][json-string] | | Binary | [string][json-string], [Base64-encoded][base64] binary | @@ -93,14 +93,14 @@ respective CloudEvents type when the mapping rules are fulfilled. The following table shows exemplary attribute mappings: -| CloudEvents | Type | Exemplary JSON Value | -| --------------- | ------------- | ------------------------------- | -| type | String | "com.example.someevent" | -| specversion | String | "1.0-rc1" | -| source | URI-reference | "/mycontext" | -| id | String | "1234-1234-1234" | -| time | Timestamp | "2018-04-05T17:31:00Z" | -| datacontenttype | String | "application/json" | +| CloudEvents | Type | Exemplary JSON Value | +| --------------- | ------------- | ----------------------- | +| type | String | "com.example.someevent" | +| specversion | String | "1.0-rc1" | +| source | URI-reference | "/mycontext" | +| id | String | "1234-1234-1234" | +| time | Timestamp | "2018-04-05T17:31:00Z" | +| datacontenttype | String | "application/json" | ### 2.4. JSONSchema Validation @@ -120,26 +120,26 @@ the [type system mapping](#22-type-system-mapping). ### 3.1. Handling of "data" -Before taking action, a JSON serializer MUST first determine the runtime data -type of the `data` content. +Before taking action, a JSON serializer MUST first determine the runtime data +type of the `data` content. 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 +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. +to store it inside the JSON object. -For any other type, the implementation MUST translate the `data` value into +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. +to store it inside the JSON object. Out of this follows that use of the `data` and `data_base64` members is -mutually exclusive in a JSON serialized CloudEvent. +mutually exclusive in a JSON serialized CloudEvent. 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. +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. Unlike attributes, for which value types are restricted to strings per the [type-system mapping](#22-type-system-mapping), the resulting `data` member @@ -284,8 +284,7 @@ also valid in a request): [ce-types]: ./spec.md#type-system [content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 [json-format]: ./json-format.md -[json-geoseq]: - https://www.iana.org/assignments/media-types/application/geo+json-seq +[json-geoseq]: https://www.iana.org/assignments/media-types/application/geo+json-seq [json-object]: https://tools.ietf.org/html/rfc7159#section-4 [json-seq]: https://www.iana.org/assignments/media-types/application/json-seq [json-bool]: https://tools.ietf.org/html/rfc7159#section-3 diff --git a/kafka-protocol-binding.md b/kafka-protocol-binding.md index f8328d778..18008f57c 100644 --- a/kafka-protocol-binding.md +++ b/kafka-protocol-binding.md @@ -2,8 +2,8 @@ ## Abstract -The [Kafka][Kafka] Protocol Binding for CloudEvents defines how events are -mapped to [Kafka messages][Kafka-Message-Format]. +The [Kafka][kafka] Protocol Binding for CloudEvents defines how events are +mapped to [Kafka messages][kafka-message-format]. ## Status of this document @@ -12,62 +12,68 @@ This document is a working draft. ## Table of Contents 1. [Introduction](#1-introduction) + - 1.1. [Conformance](#11-conformance) - 1.2. [Relation to Kafka](#12-relation-to-kafka) - 1.3. [Content Modes](#13-content-modes) - 1.4. [Event Formats](#14-event-formats) - 1.5. [Security](#15-security) + 2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) + - 2.1. [data](#21-data) + 3. [Kafka Message Mapping](#3-kafka-message-mapping) + - 3.1. [Key Attribute](#31-key-attribute) - 3.2. [Binary Content Mode](#32-binary-content-mode) - 3.3. [Structured Content Mode](#33-structured-content-mode) + 4. [References](#4-references) ## 1. Introduction -[CloudEvents][CE] is a standardized and protocol-agnostic definition of the +[CloudEvents][ce] is a standardized and protocol-agnostic definition of the structure and metadata description of events. This specification defines how the elements defined in the CloudEvents specification are to be used in the -Kafka protocol as [Kafka messages][Kafka-Message-Format] (aka Kafka records). +Kafka protocol as [Kafka messages][kafka-message-format] (aka Kafka records). ### 1.1. Conformance The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC2119][RFC2119]. +interpreted as described in [RFC2119][rfc2119]. ### 1.2. Relation to Kafka This specification does not prescribe rules constraining transfer or settlement of event messages with Kafka; it solely defines how CloudEvents are expressed -in the Kafka protocol as [Kafka messages][Kafka-Message-Format]. +in the Kafka protocol as [Kafka messages][kafka-message-format]. ### 1.3. Content Modes The specification defines two content modes for transferring events: -*structured* and *binary*. +_structured_ and _binary_. -In the *structured* content mode, event metadata attributes and event data are +In the _structured_ content mode, event metadata attributes and event data are placed into the Kafka message value section using an [event format](#14-event-formats). -In the *binary* content mode, the value of the event `data` MUST be placed into +In the _binary_ content mode, the value of the event `data` MUST be placed into the Kafka message's value section as-is, with the `content-type` header value declaring its media type; all other event attributes MUST be mapped to the -Kafka message's [header section][Kafka-Message-Header]. +Kafka message's [header section][kafka-message-header]. -Implementations that use Kafka 0.11.0.0 and above MAY use either *binary* -or *structured* modes. Implementations that use Kafka 0.10.x.x and below -MUST use only use *structured* mode and encode the event in JSON. This is +Implementations that use Kafka 0.11.0.0 and above MAY use either _binary_ +or _structured_ modes. Implementations that use Kafka 0.10.x.x and below +MUST use only use _structured_ mode and encode the event in JSON. This is because older versions of Kafka lacked support for message level headers. ### 1.4. Event Formats -Event formats, used with the *structured* content mode, define how an event is +Event formats, used with the _structured_ content mode, define how an event is expressed in a particular data format. All implementations of this -specification MUST support the [JSON event format][JSON-format]. +specification MUST support the [JSON event format][json-format]. ### 1.5. Security @@ -76,7 +82,7 @@ mandate specific existing features to be used. ## 2. Use of CloudEvents Attributes -This specification does not further define any of the [CloudEvents][CE] event +This specification does not further define any of the [CloudEvents][ce] event attributes. ### 2.1. data @@ -90,7 +96,7 @@ specification, core Kafka provides data available as a sequence of bytes. For instance, if the declared `datacontenttype` is `application/json;charset=utf-8`, the expectation is that the `data` -value is made available as [UTF-8][RFC3629] encoded JSON text. +value is made available as [UTF-8][rfc3629] encoded JSON text. ## 3. Kafka Message Mapping @@ -100,11 +106,11 @@ particular content mode might be defined by an application, but are not defined here. The receiver of the event can distinguish between the two content modes by -inspecting the `content-type` [Header][Kafka-Message-Header] of the +inspecting the `content-type` [Header][kafka-message-header] of the Kafka message. If the header is present and its value is prefixed with the CloudEvents media type `application/cloudevents`, indicating the use of a known -[event format](#14-event-formats), the receiver uses *structured* mode, -otherwise it defaults to *binary* mode. +[event format](#14-event-formats), the receiver uses _structured_ mode, +otherwise it defaults to _binary_ mode. If a receiver finds a CloudEvents media type as per the above rule, but with an event format that it cannot handle, for instance @@ -112,9 +118,10 @@ event format that it cannot handle, for instance forward it to another party as-is. If the `content-type` header is not present then the receiver uses -*structured* mode with the JSON event format. +_structured_ mode with the JSON event format. ### 3.1. Key Attribute + The 'key' attribute is populated by a partitionKeyExtractor function. The partitionKeyExtractor is a protocol specific function that contains bespoke logic to extract and populate the value. A default implementation of the @@ -123,15 +130,14 @@ value. ### 3.2. Binary Content Mode -The *binary* content mode accommodates any shape of event data, and allows for +The _binary_ content mode accommodates any shape of event data, and allows for efficient transfer and without transcoding effort. #### 3.2.1. Content Type -For the *binary* mode, the header `content-type` property MUST be mapped +For the _binary_ mode, the header `content-type` property MUST be mapped directly to the CloudEvents `datacontenttype` attribute. - #### 3.2.2. Event Data Encoding The [`data`](#21-data) byte-sequence MUST be used as the value of the Kafka @@ -139,7 +145,7 @@ message. #### 3.2.3. Metadata Headers -All [CloudEvents][CE] attributes and +All [CloudEvents][ce] attributes and [CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) with exception of `data` MUST be individually mapped to and from the Header fields in the Kafka message. @@ -147,7 +153,7 @@ fields in the Kafka message. ##### 3.2.3.1 Property Names CloudEvent attributes are prefixed with `ce_` for use in the -[message-headers][Kafka-Message-Header] section. +[message-headers][kafka-message-header] section. Examples: @@ -159,19 +165,18 @@ Examples: The value for each Kafka header is constructed from the respective header's Kafka representation, compliant with the [Kafka message -format][Kafka-Message-Format] specification. - +format][kafka-message-format] specification. #### 3.2.5 Example -This example shows the *binary* mode mapping of an event into the +This example shows the _binary_ mode mapping of an event into the Kafka message. All other CloudEvents attributes are mapped to Kafka Header fields with prefix `ce_`. Mind that `ce_` here does refer to the event `data` content carried in the payload. -``` text +```text ------------------ Message ------------------- Topic Name: mytopic @@ -199,7 +204,7 @@ content-type: application/avro ### 3.3. Structured Content Mode -The *structured* content mode keeps event metadata and data together in the +The _structured_ content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing hops, and across multiple protocols. @@ -208,9 +213,9 @@ hops, and across multiple protocols. If present, the Kafka message header property `content-type` MUST be set to the media type of an [event format](#14-event-formats). -Example for the [JSON format][JSON-format]: +Example for the [JSON format][json-format]: -``` text +```text content-type: application/cloudevents+json; charset=UTF-8 ``` @@ -232,7 +237,7 @@ Implementations MAY include the same Kafka headers as defined for the This example shows a JSON event format encoded event: -``` text +```text ------------------ Message ------------------- Topic Name: mytopic @@ -267,22 +272,22 @@ content-type: application/cloudevents+json; charset=UTF-8 ## 4. References -- [Kafka][Kafka] The distributed stream platform -- [Kafka-Message-Format][Kafka-Message-Format] The Kafka format message -- [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: +- [Kafka][kafka] The distributed stream platform +- [Kafka-Message-Format][kafka-message-format] The Kafka format message +- [RFC2046][rfc2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types -- [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels -- [RFC3629][RFC3629] UTF-8, a transformation format of ISO 10646 -- [RFC7159][RFC7159] The JavaScript Object Notation (JSON) Data Interchange +- [RFC2119][rfc2119] Key words for use in RFCs to Indicate Requirement Levels +- [RFC3629][rfc3629] UTF-8, a transformation format of ISO 10646 +- [RFC7159][rfc7159] The JavaScript Object Notation (JSON) Data Interchange Format -[CE]: ./spec.md -[JSON-format]: ./json-format.md -[Kafka]: https://kafka.apache.org -[Kafka-Message-Format]: https://kafka.apache.org/documentation/#messageformat -[Kafka-Message-Header]: https://kafka.apache.org/documentation/#recordheader -[JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3 -[RFC2046]: https://tools.ietf.org/html/rfc2046 -[RFC2119]: https://tools.ietf.org/html/rfc2119 -[RFC3629]: https://tools.ietf.org/html/rfc3629 -[RFC7159]: https://tools.ietf.org/html/rfc7159 +[ce]: ./spec.md +[json-format]: ./json-format.md +[kafka]: https://kafka.apache.org +[kafka-message-format]: https://kafka.apache.org/documentation/#messageformat +[kafka-message-header]: https://kafka.apache.org/documentation/#recordheader +[json-value]: https://tools.ietf.org/html/rfc7159#section-3 +[rfc2046]: https://tools.ietf.org/html/rfc2046 +[rfc2119]: https://tools.ietf.org/html/rfc2119 +[rfc3629]: https://tools.ietf.org/html/rfc3629 +[rfc7159]: https://tools.ietf.org/html/rfc7159 diff --git a/mqtt-protocol-binding.md b/mqtt-protocol-binding.md index 9e39fa36b..a95f1706b 100644 --- a/mqtt-protocol-binding.md +++ b/mqtt-protocol-binding.md @@ -316,8 +316,7 @@ Topic Name: mytopic [json-format]: ./json-format.md [oasis-mqtt-3.1.1]: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html [oasis-mqtt-5]: http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html -[5-content-type]: - http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html#_Toc502667341 +[5-content-type]: http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html#_Toc502667341 [json-value]: https://tools.ietf.org/html/rfc7159#section-3 [rfc2046]: https://tools.ietf.org/html/rfc2046 [rfc2119]: https://tools.ietf.org/html/rfc2119 diff --git a/roadmap.md b/roadmap.md index b140f9cd2..76c2d38fe 100644 --- a/roadmap.md +++ b/roadmap.md @@ -73,6 +73,7 @@ _1.0-rc1_ - Completed - 2019/09/19 1. Decide on duration and exit criteria for 'verification & testing' period. _1.0_ + 1. Completion of exit criteria for 'verification & testing' period. 1. Completion of as many `try-for-v1.0` issues and PRs as possible. The expectation is that these are non-breaking changes to the core spec. @@ -80,7 +81,7 @@ _1.0_ necessary to align with the core spec. _Post 1.0_ + - All remaining issues and PRs will be examined. - How, and when, future releases (major, minor or patch) will be released will be determined by based on the set of changes that have been approved. - diff --git a/spec.md b/spec.md index a2ded1ab3..6cd494c47 100644 --- a/spec.md +++ b/spec.md @@ -123,7 +123,7 @@ information. An Event Format specifies how to serialize a CloudEvent as a sequence of bytes. Stand-alone event formats, such as the [JSON format](json-format.md), specify -serialization independent of any protocol or storage medium. Protocol Bindings +serialization independent of any protocol or storage medium. Protocol Bindings MAY define formats that are dependent on the protocol. #### Message