From 678e215dc0974918360fbf4a88934e8dee965338 Mon Sep 17 00:00:00 2001 From: Clemens Vasters Date: Wed, 31 Oct 2018 10:41:26 +0100 Subject: [PATCH 1/3] attribute names Signed-off-by: Clemens Vasters --- amqp-transport-binding.md | 40 ++++++++++++------------- http-transport-binding.md | 62 +++++++++++++++++++-------------------- json-format.md | 58 ++++++++++++++++++------------------ mqtt-transport-binding.md | 38 ++++++++++++------------ nats-transport-binding.md | 14 ++++----- spec.json | 36 +++++++++++------------ spec.md | 56 +++++++++++++++++++---------------- 7 files changed, 154 insertions(+), 150 deletions(-) diff --git a/amqp-transport-binding.md b/amqp-transport-binding.md index cd5ffed25..5f1b4c91f 100644 --- a/amqp-transport-binding.md +++ b/amqp-transport-binding.md @@ -18,7 +18,7 @@ This document is a working draft. - 1.4. [Event Formats](#14-event-formats) - 1.5. [Security](#15-security) 2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) -- 2.1. [contentType Attribute](#21-contenttype-attribute) +- 2.1. [contenttype Attribute](#21-contenttype-attribute) - 2.2. [data Attribute](#22-data-attribute) 3. [AMQP Message Mapping](#3-amqp-message-mapping) - 3.2. [Binary Content Mode](#31-binary-content-mode) @@ -65,7 +65,7 @@ using an [event format](#14-event-formats). In the *binary* content mode, the value of the event `data` attribute is placed into the AMQP message's [application data][data] section as-is, with -the `contentType` attribute value declaring its media type; all other event +the `contenttype` attribute value declaring its media type; all other event attributes are mapped to the AMQP [application-properties][app-properties] section. ### 1.4. Event Formats @@ -86,31 +86,31 @@ mandate specific existing features to be used. This specification does not further define any of the [CloudEvents][CE] event attributes. -Two of the event attributes, `contentType` and `data` are handled specially +Two of the event attributes, `contenttype` and `data` are handled specially and mapped onto AMQP 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 `contentType` and +event metadata. Any mention of event attributes other than `contenttype` and `data` is exemplary. -### 2.1. contentType Attribute +### 2.1. contenttype Attribute -The `contentType` attribute is assumed to contain a [RFC2046][RFC2046] +The `contenttype` attribute is assumed to contain a [RFC2046][RFC2046] compliant media-type expression. ### 2.2. data Attribute The `data` attribute is assumed to contain opaque application data that is -encoded as declared by the `contentType` attribute. +encoded as declared by the `contenttype` 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 available as a sequence of bytes. -For instance, if the declared `contentType` is +For instance, if the declared `contenttype` is `application/json;charset=utf-8`, the expectation is that the `data` attribute value is made available as [UTF-8][RFC3629] encoded JSON text for use in AMQP. @@ -140,7 +140,7 @@ efficient transfer and without transcoding effort. #### 3.1.1. AMQP content-type For the *binary* mode, the AMQP `content-type` property field value maps -directly to the CloudEvents `contentType` attribute. +directly to the CloudEvents `contenttype` attribute. #### 3.1.2. Event Data Encoding @@ -149,8 +149,8 @@ The [`data` attribute](#22-data-attribute) byte-sequence is used as the AMQP #### 3.1.3. Metadata Headers -All [CloudEvents][CE] attributes with exception of `contentType` and `data` -MUST be individually mapped to and from the AMQP +All [CloudEvents][CE] attributes with exception of `contenttype` and `data` +are individually mapped to and from the AMQP [application-properties][app-properties] section, with exceptions noted below. @@ -172,9 +172,9 @@ Cloud Event attributes are prefixed with "cloudEvents:" for use in the Examples: - * `eventTime` maps to `cloudEvents:eventTime` - * `eventID` maps to `cloudEvents:eventID` - * `cloudEventsVersion` maps to `cloudEvents:cloudEventsVersion` + * `eventtime` maps to `cloudEvents:eventtime` + * `eventid` maps to `cloudEvents:eventid` + * `cloudeventsversion` maps to `cloudEvents:cloudeventsversion` ##### 3.1.3.2 AMQP Application Property Values @@ -195,10 +195,10 @@ content-type: application/json; charset=utf-8 ----------- application-properties ----------- -cloudEvents:cloudEventsVersion: "0.1" -cloudEvents:eventType: "com.example.someevent" -cloudEvents:eventTime: "2018-04-05T03:56:24Z" -cloudEvents:eventID: "1234-1234-1234" +cloudEvents:cloudeventsversion: "0.1" +cloudEvents:eventtype: "com.example.someevent" +cloudEvents:eventtime: "2018-04-05T03:56:24Z" +cloudEvents:eventid: "1234-1234-1234" cloudEvents:source: "/mycontext/subcontext" .... further attributes ... @@ -257,8 +257,8 @@ content-type: application/cloudevents+json; charset=utf-8 ------------- application-data -------------------------- { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", ... further attributes omitted ... diff --git a/http-transport-binding.md b/http-transport-binding.md index 4b01658ad..fdb1d5795 100644 --- a/http-transport-binding.md +++ b/http-transport-binding.md @@ -18,7 +18,7 @@ This document is a working draft. - 1.4. [Event Formats](#14-event-formats) - 1.5. [Security](#15-security) 2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) -- 2.1. [contentType Attribute](#21-contenttype-attribute) +- 2.1. [contenttype Attribute](#21-contenttype-attribute) - 2.2. [data Attribute](#22-data-attribute) 3. [HTTP Message Mapping](#3-http-message-mapping) - 3.2. [Binary Content Mode](#31-binary-content-mode) @@ -67,7 +67,7 @@ placed into the HTTP request or response body using an [event format](#14-event-formats). In the *binary* content mode, the value of the event `data` attribute is placed -into the HTTP request or response body as-is, with the `contentType` attribute +into the HTTP request or response body as-is, with the `contenttype` attribute value declaring its media type; all other event attributes are mapped to HTTP headers. @@ -89,31 +89,31 @@ 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, `contentType` and `data` are handled specially +Two of the event attributes, `contenttype` and `data` are 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 `contentType` and +event metadata. Any mention of event attributes other than `contenttype` and `data` is exemplary. -### 2.1. contentType Attribute +### 2.1. contenttype Attribute -The `contentType` attribute is assumed to contain a [RFC2046][RFC2046] +The `contenttype` attribute is assumed to contain a [RFC2046][RFC2046] compliant media-type expression. ### 2.2. data Attribute The `data` attribute is assumed to contain opaque application data that is -encoded as declared by the `contentType` attribute. +encoded as declared by the `contenttype` 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. -For instance, if the declared `contentType` is +For instance, if the declared `contenttype` 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. @@ -144,7 +144,7 @@ efficient transfer and without transcoding effort. #### 3.1.1. HTTP Content-Type For the *binary* mode, the HTTP `Content-Type` value maps directly to the -CloudEvents `contentType` attribute. +CloudEvents `contenttype` attribute. #### 3.1.2. Event Data Encoding @@ -153,8 +153,8 @@ message body. #### 3.1.3. Metadata Headers -All [CloudEvents][CE] attributes with exception of `contentType` and `data` -MUST be individually mapped to and from distinct HTTP message headers, +All [CloudEvents][CE] attributes with exception of `contenttype` and `data` +are individually mapped to and from distinct HTTP message headers, with exceptions noted below. CloudEvents extensions that define their own attributes MAY define a @@ -172,18 +172,18 @@ the time of the submission or revision. Except for attributes [explicitly handled in this specification] (#2-use-of-cloudevents-attributes), the naming convention for the HTTP header mapping of well-known CloudEvents attributes is that -each attribute name MUST be prefixed with "CE-". +each attribute name MUST be prefixed with "ce-". Examples: - * `eventTime` maps to `CE-EventTime` - * `eventID` maps to `CE-EventID` - * `cloudEventsVersion` maps to `CE-CloudEventsVersion` + * `eventtime` maps to `ce-eventtime` + * `eventid` maps to `ce-eventid` + * `cloudeventsversion` maps to `ce-cloudeventsversion` `Map`-typed CloudEvents attributes MUST be flattened into a set of HTTP headers, where by the name of each header carries the prefix -"CE-", an infix reflecting the map attribute followed by a dash -("-"), and the name of the map entry key, e.g. "CE-attrib-key". +"ce-", an infix reflecting the map attribute followed by a dash +("-"), and the name of the map entry key, e.g. "ce-attrib-key". Note: per the [HTTP](https://tools.ietf.org/html/rfc7230#section-3.2) specification, header names are case-insensitive. @@ -220,11 +220,11 @@ request: ``` text POST /someresource HTTP/1.1 Host: webhook.example.com -CE-CloudEventsVersion: "0.1" -CE-EventType: "com.example.someevent" -CE-EventTime: "2018-04-05T03:56:24Z" -CE-EventID: "1234-1234-1234" -CE-Source: "/mycontext/subcontext" +ce-cloudeventsversion: "0.1" +ce-eventtype: "com.example.someevent" +ce-eventtime: "2018-04-05T03:56:24Z" +ce-eventid: "1234-1234-1234" +ce-source: "/mycontext/subcontext" .... further attributes ... Content-Type: application/json; charset=utf-8 Content-Length: nnnn @@ -238,11 +238,11 @@ This example shows a response containing an event: ``` text HTTP/1.1 200 OK -CE-CloudEventsVersion: "0.1" -CE-EventType: "com.example.someevent" -CE-EventTime: "2018-04-05T03:56:24Z" -CE-EventID: "1234-1234-1234" -CE-Source: "/mycontext/subcontext" +ce-cloudeventsversion: "0.1" +ce-eventtype: "com.example.someevent" +ce-eventtime: "2018-04-05T03:56:24Z" +ce-eventid: "1234-1234-1234" +ce-source: "/mycontext/subcontext" .... further attributes ... Content-Type: application/json; charset=utf-8 Content-Length: nnnn @@ -297,8 +297,8 @@ Content-Type: application/cloudevents+json; charset=utf-8 Content-Length: nnnn { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", ... further attributes omitted ... @@ -318,8 +318,8 @@ Content-Type: application/cloudevents+json; charset=utf-8 Content-Length: nnnn { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", ... further attributes omitted ... diff --git a/json-format.md b/json-format.md index 2208b5631..a6aa9cf19 100644 --- a/json-format.md +++ b/json-format.md @@ -95,12 +95,12 @@ The following table shows exemplary mappings: | CloudEvents | Type | Exemplary JSON Value |--------------------|----------|------------------------------- -| eventType | String | "com.example.someevent" -| cloudEventsVersion | String | "0.1" +| eventtype | String | "com.example.someevent" +| cloudeventsversion | String | "0.1" | source | URI | "/mycontext" -| eventID | String | "1234-1234-1234" -| eventTime | Timestamp| "2018-04-05T17:31:00Z" -| contentType | String | "application/json" +| eventid | String | "1234-1234-1234" +| eventtime | Timestamp| "2018-04-05T17:31:00Z" +| contenttype | String | "application/json" | data | String | "" | data | Binary | "Q2xvdWRFdmVudHM=" | data | Map | { "objA" : "vA", "objB", "vB" } @@ -128,15 +128,15 @@ in [Section 2.3.](#23-mapping-any-typed-attributes), with one additional rule: If an implementation determines that the type of the `data` attribute is -`Binary` or `String`, it MUST inspect the `contentType` attribute to determine +`Binary` or `String`, it MUST inspect the `contenttype` attribute to determine whether it is indicated that the data value contains JSON data. -If the `contentType` value is either ["application/json"][RFC4627] or any media type +If the `contenttype` 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 `contentType` value does not follow the [structured +json suffix][RFC6839] +If the `contenttype` 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, @@ -154,16 +154,16 @@ Example event with `String`-valued `data`: ``` JSON { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", "source" : "/mycontext", - "eventID" : "A234-1234-1234", - "eventTime" : "2018-04-05T17:31:00Z", - "comExampleExtension1" : "value", - "comExampleExtension2" : { + "eventid" : "A234-1234-1234", + "eventtime" : "2018-04-05T17:31:00Z", + "comexampleextension1" : "value", + "comexampleextension2" : { "otherValue": 5 }, - "contentType" : "text/xml", + "contenttype" : "text/xml", "data" : "" } ``` @@ -172,16 +172,16 @@ Example event with `Binary`-valued data ``` JSON { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", "source" : "/mycontext", - "eventID" : "B234-1234-1234", - "eventTime" : "2018-04-05T17:31:00Z", - "comExampleExtension1" : "value", - "comExampleExtension2" : { + "eventid" : "B234-1234-1234", + "eventtime" : "2018-04-05T17:31:00Z", + "comexampleextension1" : "value", + "comexampleextension2" : { "otherValue": 5 }, - "contentType" : "application/vnd.apache.thrift.binary", + "contenttype" : "application/vnd.apache.thrift.binary", "data" : "... base64 encoded string ..." } ``` @@ -191,16 +191,16 @@ a `Map` or [JSON data](#31-special-handling-of-the-data-attribute) data: ``` JSON { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", "source" : "/mycontext", - "eventID" : "C234-1234-1234", - "eventTime" : "2018-04-05T17:31:00Z", - "comExampleExtension1" : "value", - "comExampleExtension2" : { + "eventid" : "C234-1234-1234", + "eventtime" : "2018-04-05T17:31:00Z", + "comexampleextension1" : "value", + "comexampleextension2" : { "otherValue": 5 }, - "contentType" : "application/json", + "contenttype" : "application/json", "data" : { "appinfoA" : "abc", "appinfoB" : 123, diff --git a/mqtt-transport-binding.md b/mqtt-transport-binding.md index be336929f..fab55331a 100644 --- a/mqtt-transport-binding.md +++ b/mqtt-transport-binding.md @@ -19,7 +19,7 @@ This document is a working draft. - 1.4. [Event Formats](#14-event-formats) - 1.5. [Security](#15-security) 2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) -- 2.1. [contentType Attribute](#21-contenttype-attribute) +- 2.1. [contenttype Attribute](#21-contenttype-attribute) - 2.2. [data Attribute](#22-data-attribute) 3. [MQTT PUBLISH Message Mapping](#3-mqtt-publish-message-mapping) - 3.2. [Binary Content Mode](#31-binary-content-mode) @@ -59,7 +59,7 @@ using an [event format](#14-event-formats). In the *binary* content mode, the value of the event `data` attribute is placed into the MQTT PUBLISH message's payload section as-is, with -the `contentType` attribute value declaring its media type; all other event +the `contenttype` attribute value declaring its media type; all other event attributes are mapped to the MQTT PUBLISH message's [properties section][5-publish-properties]. @@ -82,31 +82,31 @@ mandate specific existing features to be used. This specification does not further define any of the [CloudEvents][CE] event attributes. -Two of the event attributes, `contentType` and `data` are handled specially +Two of the event attributes, `contenttype` and `data` are handled specially and mapped onto MQTT 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 `contentType` and +event metadata. Any mention of event attributes other than `contenttype` and `data` is exemplary. -### 2.1. contentType Attribute +### 2.1. contenttype Attribute -The `contentType` attribute is assumed to contain a [RFC2046][RFC2046] +The `contenttype` attribute is assumed to contain a [RFC2046][RFC2046] compliant media-type expression. ### 2.2. data Attribute The `data` attribute is assumed to contain opaque application data that is -encoded as declared by the `contentType` attribute. +encoded as declared by the `contenttype` attribute. An application is free to hold the information in any in-memory representation of its choosing, but as the value is transposed into MQTT as defined in this specification, the assumption is that the `data` attribute value is made available as a sequence of bytes. -For instance, if the declared `contentType` is +For instance, if the declared `contenttype` is `application/json;charset=utf-8`, the expectation is that the `data` attribute value is made available as [UTF-8][RFC3629] encoded JSON text for use in MQTT. @@ -141,7 +141,7 @@ efficient transfer and without transcoding effort. For the *binary* mode, the MQTT PUBLISH message's [`Content Type`][5-content-type] property MUST be mapped directly to the CloudEvents -`contentType` attribute. +`contenttype` attribute. #### 3.1.2. Event Data Encoding @@ -150,7 +150,7 @@ payload of the MQTT PUBLISH message. #### 3.1.3. Metadata Headers -All [CloudEvents][CE] attributes with exception of `contentType` and `data` +All [CloudEvents][CE] attributes with exception of `contenttype` and `data` MUST be individually mapped to and from the User Property fields in the MQTT PUBLISH message, with exceptions noted below. @@ -178,7 +178,7 @@ respective CloudEvents attribute's JSON type representation, compliant with the #### 3.1.4 Examples This example shows the *binary* mode mapping of an event into the -MQTT 5.0 PUBLISH message. The CloudEvents `contentType` attribute +MQTT 5.0 PUBLISH message. The CloudEvents `contenttype` attribute is mapped to the MQTT PUBLISH `Content Type` field; all other CloudEvents attributes are mapped to MQTT PUBLISH User Property fields. The `Topic name` is chosen by the MQTT client and not derived @@ -195,10 +195,10 @@ Content Type: application/json; charset=utf-8 ------------- User Properties ---------------- -cloudEventsVersion: "0.1" -eventType: "com.example.someevent" -eventTime: "2018-04-05T03:56:24Z" -eventId: "1234-1234-1234" +cloudeventsversion: "0.1" +eventtype: "com.example.someevent" +eventtime: "2018-04-05T03:56:24Z" +eventid: "1234-1234-1234" source: "/mycontext/subcontext" .... further attributes ... @@ -257,8 +257,8 @@ Content Type: application/cloudevents+json; charset=utf-8 ------------------ payload ------------------- { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", ... further attributes omitted ... @@ -282,8 +282,8 @@ Topic Name: mytopic ------------------ payload ------------------- { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", ... further attributes omitted ... diff --git a/nats-transport-binding.md b/nats-transport-binding.md index 3a3b4069b..02e7a1181 100644 --- a/nats-transport-binding.md +++ b/nats-transport-binding.md @@ -17,7 +17,7 @@ This document is a working draft. - 1.4. [Event Formats](#14-event-formats) - 1.5. [Security](#15-security) 2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) -- 2.1. [contentType Attribute](#21-contenttype-attribute) +- 2.1. [contenttype Attribute](#21-contenttype-attribute) - 2.2. [data Attribute](#22-data-attribute) 3. [NATS Message Mapping](#3-nats-message-mapping) - 3.1. [Event Data Encoding](#31-event-data-encoding) @@ -73,21 +73,21 @@ mandate specific existing features to be used. This specification does not further define any of the [CloudEvents][CE] event attributes. -### 2.1. contentType Attribute +### 2.1. contenttype Attribute -The `contentType` attribute is assumed to contain a media-type expression +The `contenttype` attribute is assumed to contain a media-type expression compliant with [RFC2046][RFC2046]. ### 2.2. data Attribute The `data` attribute is assumed to contain opaque application data that is -encoded as declared by the `contentType` attribute. +encoded as declared by the `contenttype` attribute. An application is free to hold the information in any in-memory representation of its choosing, but as the value is transposed into NATS as defined in this specification, core NATS provides data available as a sequence of bytes. -For instance, if the declared `contentType` is +For instance, if the declared `contenttype` is `application/json;charset=utf-8`, the expectation is that the `data` attribute value is made available as [UTF-8][RFC3629] encoded JSON text. @@ -122,8 +122,8 @@ Subject: mySubject ------------------ payload ------------------- { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", ... further attributes omitted ... diff --git a/spec.json b/spec.json index 0303aab02..40bc67f66 100644 --- a/spec.json +++ b/spec.json @@ -1,10 +1,10 @@ { "$ref": "#/definitions/event", "definitions": { - "cloudEventsVersion": { + "cloudeventsversion": { "type": "string" }, - "contentType": { + "contenttype": { "type": "string" }, "data": { @@ -15,23 +15,23 @@ }, "event": { "properties": { - "cloudEventsVersion": { - "$ref": "#/definitions/cloudEventsVersion" + "cloudeventsversion": { + "$ref": "#/definitions/cloudeventsversion" }, - "contentType": { - "$ref": "#/definitions/contentType" + "contenttype": { + "$ref": "#/definitions/contenttype" }, "data": { "$ref": "#/definitions/data" }, - "eventID": { - "$ref": "#/definitions/eventID" + "eventid": { + "$ref": "#/definitions/eventid" }, - "eventTime": { - "$ref": "#/definitions/eventTime" + "eventtime": { + "$ref": "#/definitions/eventtime" }, - "eventType": { - "$ref": "#/definitions/eventType" + "eventtype": { + "$ref": "#/definitions/eventtype" }, "extensions": { "$ref": "#/definitions/extensions" @@ -41,21 +41,21 @@ } }, "required": [ - "cloudEventsVersion", - "eventID", - "eventType", + "cloudeventsversion", + "eventid", + "eventtype", "source" ], "type": "object" }, - "eventID": { + "eventid": { "type": "string" }, - "eventTime": { + "eventtime": { "format": "date-time", "type": "string" }, - "eventType": { + "eventtype": { "type": "string" }, "extensions": { diff --git a/spec.md b/spec.md index eb5b66869..93b5bb787 100644 --- a/spec.md +++ b/spec.md @@ -49,15 +49,19 @@ be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). ### Attribute Naming Convention -CloudEvents attributes use "camelCasing" for the object member names, to aid -integration with common programming languages. - -Attribute names that are composed of multiple words are expressed as compound -words, with the first word starting with a lower-case character and all -subsequent words starting with an upper-case character, and no separator -characters. - -Words that are acronyms are written in all-caps, e.g. "ID" and "URL". +The CloudEvents specifications define mappings to various protocols and +encodings, and the accompanying CloudEvents SDK targets various runtimes and +languages. Some of these treat metadata elements as case-sensitive while others +do not, and a single CloudEvent might be routed via multiple hops that involve +a mix of protocols, encodings, and runtimes. Therefore, this specification +limits the available character set of all normatively named attributes such that +case-sensitivity issues or clashes with the permissible character set for +identifiers in common languages are prevented. + +CloudEvents attribute names MUST consist of lower-case letters ('a' to 'z') +or digits ('0' to '9') from the ASCII character set, and MUST begin with a +lower-case letter. Attribute names SHOULD be descriptive and terse, and SHOULD +NOT exceed 20 characters in length. ### Terminology @@ -170,7 +174,7 @@ event consumers can easily access this information without needing to decode and examine the event data. Such identity attributes can also be used to help intermediate gateways determine how to route the events. -### eventType +### eventtype * Type: `String` * Description: Type of occurrence which has happened. Often this attribute is used for routing, observability, policy enforcement, etc. @@ -182,7 +186,7 @@ help intermediate gateways determine how to route the events. * Examples * com.github.pull.create -### cloudEventsVersion +### cloudeventsversion * Type: `String` * Description: The version of the CloudEvents specification which the event uses. This enables the interpretation of the context. @@ -199,7 +203,7 @@ help intermediate gateways determine how to route the events. * Constraints: * REQUIRED -### eventID +### eventid * Type: `String` * Description: ID of the event. The semantics of this string are explicitly undefined to ease the implementation of producers. Enables deduplication. @@ -210,7 +214,7 @@ help intermediate gateways determine how to route the events. * MUST be a non-empty string * MUST be unique within the scope of the producer -### eventTime +### eventtime * Type: `Timestamp` * Description: Timestamp of when the event happened. * Constraints: @@ -218,7 +222,7 @@ help intermediate gateways determine how to route the events. * If present, MUST adhere to the format specified in [RFC 3339](https://tools.ietf.org/html/rfc3339) -### schemaURL +### schemaurl * Type: `URI` * Description: A link to the schema that the `data` attribute adheres to. Incompatible changes to the schema SHOULD be reflected by a different URL. @@ -227,7 +231,7 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. * If present, MUST adhere to the format specified in [RFC 3986](https://tools.ietf.org/html/rfc3986) -### contentType +### contenttype * Type: `String` per [RFC 2046](https://tools.ietf.org/html/rfc2046) * Description: Content type of the `data` attribute value. This attribute enables the `data` attribute to carry any type of content, whereby format @@ -236,7 +240,7 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. format might carry an XML payload in its `data` attribute, and the consumer is informed by this attribute being set to "application/xml". The rules for how the `data` attribute content is rendered for different - `contentType` values are defined in the event format specifications; for + `contenttype` 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-the-data-attribute). @@ -265,9 +269,9 @@ encapsulated within the `data` attribute. ### data * Type: `Any` -* Description: The event payload. The payload depends on the eventType and +* Description: The event payload. The payload depends on the eventtype and the schemaURL. It is encoded into a media format - which is specified by the contentType attribute (e.g. application/json). + which is specified by the contenttype attribute (e.g. application/json). * Constraints: * OPTIONAL @@ -277,16 +281,16 @@ The following example shows a CloudEvent serialized as JSON: ``` JSON { - "cloudEventsVersion" : "0.1", - "eventType" : "com.example.someevent", + "cloudeventsversion" : "0.1", + "eventtype" : "com.example.someevent", "source" : "/mycontext", - "eventID" : "A234-1234-1234", - "eventTime" : "2018-04-05T17:31:00Z", - "comExampleExtension1" : "value", - "comExampleExtension2" : { - "otherValue": 5 + "eventid" : "A234-1234-1234", + "eventtime" : "2018-04-05T17:31:00Z", + "comexampleextension1" : "value", + "comexampleextension2" : { + "othervalue": 5 }, - "contentType" : "text/xml", + "contenttype" : "text/xml", "data" : "" } ``` From ca8eed86b98bc0039aec4d56c730081a7bab4c6a Mon Sep 17 00:00:00 2001 From: Clemens Vasters Date: Wed, 31 Oct 2018 17:31:44 +0100 Subject: [PATCH 2/3] dropping 'normatively named' restriction Signed-off-by: Clemens Vasters --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 93b5bb787..441cb9aff 100644 --- a/spec.md +++ b/spec.md @@ -54,7 +54,7 @@ encodings, and the accompanying CloudEvents SDK targets various runtimes and languages. Some of these treat metadata elements as case-sensitive while others do not, and a single CloudEvent might be routed via multiple hops that involve a mix of protocols, encodings, and runtimes. Therefore, this specification -limits the available character set of all normatively named attributes such that +limits the available character set of all attributes such that case-sensitivity issues or clashes with the permissible character set for identifiers in common languages are prevented. From 19950a1d5ccaf9be4c42d4451015247fdbb45fc0 Mon Sep 17 00:00:00 2001 From: Clemens Vasters Date: Wed, 31 Oct 2018 17:37:39 +0100 Subject: [PATCH 3/3] fixing merge bugs Signed-off-by: Clemens Vasters --- amqp-transport-binding.md | 2 +- http-transport-binding.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/amqp-transport-binding.md b/amqp-transport-binding.md index 5f1b4c91f..24d163744 100644 --- a/amqp-transport-binding.md +++ b/amqp-transport-binding.md @@ -150,7 +150,7 @@ The [`data` attribute](#22-data-attribute) byte-sequence is used as the AMQP #### 3.1.3. Metadata Headers All [CloudEvents][CE] attributes with exception of `contenttype` and `data` -are individually mapped to and from the AMQP +MUST be individually mapped to and from the AMQP [application-properties][app-properties] section, with exceptions noted below. diff --git a/http-transport-binding.md b/http-transport-binding.md index fdb1d5795..e100f8049 100644 --- a/http-transport-binding.md +++ b/http-transport-binding.md @@ -154,7 +154,7 @@ message body. #### 3.1.3. Metadata Headers All [CloudEvents][CE] attributes with exception of `contenttype` and `data` -are individually mapped to and from distinct HTTP message headers, +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