From 4e8df985f3eae1fb257ecd178ebb6495bcfa8adc Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 27 Jun 2018 16:36:56 -0700 Subject: [PATCH 01/16] Add property attribute Signed-off-by: cathyhongzhang --- json-format.md | 6 +++--- spec.md | 35 +++++++++++++++++++++++------------ 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/json-format.md b/json-format.md index cc66fc7cf..d278ca630 100644 --- a/json-format.md +++ b/json-format.md @@ -140,7 +140,7 @@ Example event with `String`-valued `data`: "source" : "/mycontext", "eventID" : "A234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "extensions" : { + "properties" : { "comExampleExtension" : "value" }, "contentType" : "text/xml", @@ -157,7 +157,7 @@ Example event with `Binary`-valued data "source" : "/mycontext", "eventID" : "B234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "extensions" : { + "properties" : { "comExampleExtension" : "value" }, "contentType" : "application/vnd.apache.thrift.binary", @@ -175,7 +175,7 @@ a `Map` or [JSON data](#31-special-handling-of-the-data-attribute) data: "source" : "/mycontext", "eventID" : "C234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "extensions" : { + "properties" : { "comExampleExtension" : "value" }, "contentType" : "application/json", diff --git a/spec.md b/spec.md index a7346981a..08e81db37 100644 --- a/spec.md +++ b/spec.md @@ -217,26 +217,37 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. or application protocol's content-type metadata property. Normative rules for the binary mode and the content-type metadata mapping can be found in the respective transport mapping specifications. - + * Constraints: * OPTIONAL * If present, MUST adhere to the format specified in [RFC 2046](https://tools.ietf.org/html/rfc2046) * For Media Type examples see [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) -### extensions +### properties * Type: `Map` -* Description: This is for additional metadata and this does not have a - mandated structure. This enables a place for custom fields a producer or - middleware might want to include and provides a place to test metadata before - adding them to the CloudEvents specification. - See the [Extensions](extensions.md) document for a list of possible - attributes. +* Description: This is a place for custom key-value pairs a producer or + middleware want to include to provide more information about the + event. It does not have mandated definition of the keys. + For example, a producer could put an event identification label + which will be used by a serverless platform to correlate this event + with other types of events associated with the same application + workflow instance. When adding a new key-value pair, + care should be taken to use a name that is descriptive enough and + not overlapping with the other keys. The extensions.md document + contains some possible attributes that could be used as the keys, + but producers are free to define their own. * Constraints: - * OPTIONAL + * OPTIONAL * If present, MUST contain at least one entry * Examples: - * authorization data +``` JSON + properties + { + "employee-ID": "H0098002", + "travel-request-ID": "123456" + } +``` ## Data Attribute @@ -263,8 +274,8 @@ The following example shows a CloudEvent serialized as JSON: "source" : "/mycontext", "eventID" : "A234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "extensions" : { - "comExampleExtension" : "value" + "properties" : { + "employee-ID": "H0098002" }, "contentType" : "text/xml", "data" : "" From 250d2d6f551bf3a657ca85468a528c7f37b4a527 Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 18 Jul 2018 16:45:13 -0700 Subject: [PATCH 02/16] Add properties attribute Signed-off-by: cathyhongzhang --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 08e81db37..961d2c2fb 100644 --- a/spec.md +++ b/spec.md @@ -233,12 +233,12 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. which will be used by a serverless platform to correlate this event with other types of events associated with the same application workflow instance. When adding a new key-value pair, - care should be taken to use a name that is descriptive enough and + care SHOULD be taken to use a name that is descriptive enough and not overlapping with the other keys. The extensions.md document contains some possible attributes that could be used as the keys, but producers are free to define their own. * Constraints: - * OPTIONAL + * OPTIONAL * If present, MUST contain at least one entry * Examples: ``` JSON From f09f0c429d05df6e1554ce47383d5bc8b29aa021 Mon Sep 17 00:00:00 2001 From: cathy Date: Thu, 26 Jul 2018 09:42:24 -0700 Subject: [PATCH 03/16] Update spec.md --- spec.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 961d2c2fb..14d6dffb9 100644 --- a/spec.md +++ b/spec.md @@ -224,19 +224,17 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. [RFC 2046](https://tools.ietf.org/html/rfc2046) * For Media Type examples see [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) -### properties +### identificationLabels * Type: `Map` * Description: This is a place for custom key-value pairs a producer or - middleware want to include to provide more information about the - event. It does not have mandated definition of the keys. + middleware want to include to provide more identification information + about the event. It does not have mandated definition of the keys. For example, a producer could put an event identification label which will be used by a serverless platform to correlate this event with other types of events associated with the same application workflow instance. When adding a new key-value pair, care SHOULD be taken to use a name that is descriptive enough and - not overlapping with the other keys. The extensions.md document - contains some possible attributes that could be used as the keys, - but producers are free to define their own. + not overlapping with the other keys. * Constraints: * OPTIONAL * If present, MUST contain at least one entry @@ -249,6 +247,8 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. } ``` +### extensions + ## Data Attribute As defined by the term [Data](#data), CloudEvents MAY include domain-specific From 44966ecfa01766c18ecdf558abd21358e52e3409 Mon Sep 17 00:00:00 2001 From: cathy Date: Thu, 26 Jul 2018 09:44:53 -0700 Subject: [PATCH 04/16] Update json-format.md --- json-format.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/json-format.md b/json-format.md index d278ca630..cc66fc7cf 100644 --- a/json-format.md +++ b/json-format.md @@ -140,7 +140,7 @@ Example event with `String`-valued `data`: "source" : "/mycontext", "eventID" : "A234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "properties" : { + "extensions" : { "comExampleExtension" : "value" }, "contentType" : "text/xml", @@ -157,7 +157,7 @@ Example event with `Binary`-valued data "source" : "/mycontext", "eventID" : "B234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "properties" : { + "extensions" : { "comExampleExtension" : "value" }, "contentType" : "application/vnd.apache.thrift.binary", @@ -175,7 +175,7 @@ a `Map` or [JSON data](#31-special-handling-of-the-data-attribute) data: "source" : "/mycontext", "eventID" : "C234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "properties" : { + "extensions" : { "comExampleExtension" : "value" }, "contentType" : "application/json", From 350f4d39162281a7ec1a978dd25aa86bca4d6f70 Mon Sep 17 00:00:00 2001 From: cathy Date: Thu, 26 Jul 2018 09:47:04 -0700 Subject: [PATCH 05/16] Update spec.md --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 14d6dffb9..5f6599502 100644 --- a/spec.md +++ b/spec.md @@ -274,7 +274,7 @@ The following example shows a CloudEvent serialized as JSON: "source" : "/mycontext", "eventID" : "A234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "properties" : { + "identificationLabels" : { "employee-ID": "H0098002" }, "contentType" : "text/xml", From 621462b3330421619c61efdf248c0e8748cb46d0 Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 8 Aug 2018 15:08:43 -0700 Subject: [PATCH 06/16] Add identityLabels attribute --- spec.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/spec.md b/spec.md index 961d2c2fb..ea8a333e2 100644 --- a/spec.md +++ b/spec.md @@ -224,19 +224,20 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. [RFC 2046](https://tools.ietf.org/html/rfc2046) * For Media Type examples see [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) -### properties +### idendityLabels * Type: `Map` * Description: This is a place for custom key-value pairs a producer or - middleware want to include to provide more information about the - event. It does not have mandated definition of the keys. - For example, a producer could put an event identification label - which will be used by a serverless platform to correlate this event - with other types of events associated with the same application - workflow instance. When adding a new key-value pair, - care SHOULD be taken to use a name that is descriptive enough and - not overlapping with the other keys. The extensions.md document - contains some possible attributes that could be used as the keys, - but producers are free to define their own. + middleware wants to include to provide additional identity information + about the event. The syntax and semantics of each specific label + inside this bucket are open for each event type producer to define + and will not be defined by this specification. + For example, a travel request messaging event producer could put + "TravelRequestID: 123456" as an identity label for a travel + request event, a home IoT device event producer could put + "home address: 20 Spruce Street, San Jose, CA" as an identity label + for that IoT device event. Identity labels could be used by a + serverless platform to correlate this event with other types of + events associated with the same serverless application instance. * Constraints: * OPTIONAL * If present, MUST contain at least one entry From 6f6fdf4e35883b36ccfa8d8ed4b800ada028529e Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 8 Aug 2018 15:42:03 -0700 Subject: [PATCH 07/16] Add identityLabels attribute Signed-off-by: cathyhongzhang --- spec.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/spec.md b/spec.md index 25cbba179..ba43e4f6e 100644 --- a/spec.md +++ b/spec.md @@ -224,6 +224,8 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. [RFC 2046](https://tools.ietf.org/html/rfc2046) * For Media Type examples see [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) +### extensions + ### idendityLabels * Type: `Map` * Description: This is a place for custom key-value pairs a producer or @@ -250,8 +252,6 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. } ``` -### extensions - ## Data Attribute As defined by the term [Data](#data), CloudEvents MAY include domain-specific @@ -277,8 +277,9 @@ The following example shows a CloudEvent serialized as JSON: "source" : "/mycontext", "eventID" : "A234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "identificationLabels" : { - "employee-ID": "H0098002" + "identityLabels" : { + "employee-ID": "H0098002", + "travel-request-ID": "123456" }, "contentType" : "text/xml", "data" : "" From 310d5fee7031fafd035fcd741784bd08b0ac87c2 Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 8 Aug 2018 15:44:42 -0700 Subject: [PATCH 08/16] Add identityLabels attribute Signed-off-by: cathyhongzhang --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index ba43e4f6e..12c7cb29e 100644 --- a/spec.md +++ b/spec.md @@ -279,7 +279,7 @@ The following example shows a CloudEvent serialized as JSON: "eventTime" : "2018-04-05T17:31:00Z", "identityLabels" : { "employee-ID": "H0098002", - "travel-request-ID": "123456" + "travel-request-ID": "123456" }, "contentType" : "text/xml", "data" : "" From d0b107d091166b375695285a528b94fb14918e0e Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 8 Aug 2018 16:43:14 -0700 Subject: [PATCH 09/16] Add identityLabels attribute Signed-off-by: cathyhongzhang --- spec.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec.md b/spec.md index 12c7cb29e..2d34e6727 100644 --- a/spec.md +++ b/spec.md @@ -277,6 +277,9 @@ The following example shows a CloudEvent serialized as JSON: "source" : "/mycontext", "eventID" : "A234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", + "extensions" : { + "comExampleExtension" : "value" + }, "identityLabels" : { "employee-ID": "H0098002", "travel-request-ID": "123456" From 7f8812a6b1f3dc4c09b34b9e093b24e7c81f885a Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 8 Aug 2018 16:47:08 -0700 Subject: [PATCH 10/16] Add identityLabels attribute Signed-off-by: cathyhongzhang --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 2d34e6727..448a01b38 100644 --- a/spec.md +++ b/spec.md @@ -277,8 +277,8 @@ The following example shows a CloudEvent serialized as JSON: "source" : "/mycontext", "eventID" : "A234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "extensions" : { - "comExampleExtension" : "value" + "extensions" : { + "comExampleExtension" : "value" }, "identityLabels" : { "employee-ID": "H0098002", From 0ac9c1135d00bceafa66e881ed886b92dab8318d Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Fri, 10 Aug 2018 11:45:43 -0700 Subject: [PATCH 11/16] Add identityLabels attribute Signed-off-by: cathyhongzhang --- spec.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 448a01b38..e411504cd 100644 --- a/spec.md +++ b/spec.md @@ -231,8 +231,9 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. * Description: This is a place for custom key-value pairs a producer or middleware wants to include to provide additional identity information about the event. The syntax and semantics of each specific label - inside this bucket are open for each event type producer to define - and will not be defined by this specification. + inside this map are open for each event type producer to define, + but the keys of this map are of type string and + the values are restricted to be of simple types only. For example, a travel request messaging event producer could put "TravelRequestID: 123456" as an identity label for a travel request event, a home IoT device event producer could put From ac688214876f8384266d77052cd2fe7a87d8b7c0 Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 29 Aug 2018 12:01:35 -0700 Subject: [PATCH 12/16] Add identityLabels attribute Signed-off-by: cathyhongzhang --- spec.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/spec.md b/spec.md index e411504cd..cbe220052 100644 --- a/spec.md +++ b/spec.md @@ -232,8 +232,7 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. middleware wants to include to provide additional identity information about the event. The syntax and semantics of each specific label inside this map are open for each event type producer to define, - but the keys of this map are of type string and - the values are restricted to be of simple types only. + but the key is a string and the value is a string. For example, a travel request messaging event producer could put "TravelRequestID: 123456" as an identity label for a travel request event, a home IoT device event producer could put From 39de3509af6e007e7c4a1013e9c2983645fa6ca1 Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 29 Aug 2018 12:37:05 -0700 Subject: [PATCH 13/16] Add identityLabels attibute Signed-off-by: cathyhongzhang --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index cbe220052..9982adeb0 100644 --- a/spec.md +++ b/spec.md @@ -226,7 +226,7 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. ### extensions -### idendityLabels +### identityLabels * Type: `Map` * Description: This is a place for custom key-value pairs a producer or middleware wants to include to provide additional identity information From cb82076719c424d78d3e61deaae27064457b2407 Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Tue, 4 Sep 2018 16:49:56 -0700 Subject: [PATCH 14/16] Add clarification on including additional context attribute Signed-off-by: cathyhongzhang --- spec.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/spec.md b/spec.md index 9982adeb0..d6415aa30 100644 --- a/spec.md +++ b/spec.md @@ -128,6 +128,19 @@ variant type. Every CloudEvent conforming to this specification MUST include one or more of the following context attributes. +It could also include additional metadata in the "context attributes" that +might be used in ancillary actions related to the processing of the event. +For example, in many IoT and enterprise use cases, an event could be used in +a serverless application that performs actions across multiple types of events. +To support such use cases, the event producer will need to add additional +identity metadata to the context attributes which the event consumers can use +to correlate this event with the other events. If such identity metadata +happen to be part of the event "data", it is still suggested that the event +producer add the identity metadata to the "context attributes" so that event +consumers can easily access this information without needing to decode and +examine the event data. Such identity metadata might also be used to help +intermediate gateways determine how to route the events. + These attributes, while descriptive of the event, are designed such that they can be serialized independent of the event data. This allows for them to be inspected at the destination without having to deserialize the event data. From 0cddc05bafde50fdb12391bacfa2122e0d25f63b Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Tue, 4 Sep 2018 17:07:04 -0700 Subject: [PATCH 15/16] Add clarification on including additional context attributes Signed-off-by: cathyhongzhang --- spec.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index d6415aa30..b33554f73 100644 --- a/spec.md +++ b/spec.md @@ -128,17 +128,17 @@ variant type. Every CloudEvent conforming to this specification MUST include one or more of the following context attributes. -It could also include additional metadata in the "context attributes" that +It could also include additional attributes in the "context attributes" that might be used in ancillary actions related to the processing of the event. For example, in many IoT and enterprise use cases, an event could be used in a serverless application that performs actions across multiple types of events. To support such use cases, the event producer will need to add additional -identity metadata to the context attributes which the event consumers can use -to correlate this event with the other events. If such identity metadata +identity attributes to the "context attributes" which the event consumers can +use to correlate this event with the other events. If such identity attributes happen to be part of the event "data", it is still suggested that the event -producer add the identity metadata to the "context attributes" so that event +producer add the identity attributes to the "context attributes" so that event consumers can easily access this information without needing to decode and -examine the event data. Such identity metadata might also be used to help +examine the event data. Such identity attributes might also be used to help intermediate gateways determine how to route the events. These attributes, while descriptive of the event, are designed such that they From 9f09651db4768f9adc7dd995804f1babcc1204f1 Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Tue, 4 Sep 2018 17:23:35 -0700 Subject: [PATCH 16/16] reverse the previous wrong commit Signed-off-by: cathyhongzhang --- spec.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/spec.md b/spec.md index b33554f73..9982adeb0 100644 --- a/spec.md +++ b/spec.md @@ -128,19 +128,6 @@ variant type. Every CloudEvent conforming to this specification MUST include one or more of the following context attributes. -It could also include additional attributes in the "context attributes" that -might be used in ancillary actions related to the processing of the event. -For example, in many IoT and enterprise use cases, an event could be used in -a serverless application that performs actions across multiple types of events. -To support such use cases, the event producer will need to add additional -identity attributes to the "context attributes" which the event consumers can -use to correlate this event with the other events. If such identity attributes -happen to be part of the event "data", it is still suggested that the event -producer add the identity attributes to the "context attributes" so that event -consumers can easily access this information without needing to decode and -examine the event data. Such identity attributes might also be used to help -intermediate gateways determine how to route the events. - These attributes, while descriptive of the event, are designed such that they can be serialized independent of the event data. This allows for them to be inspected at the destination without having to deserialize the event data.