From 9fafe98e85b0f7367005d8ca7d42f54ee9221d7b Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 5 Sep 2018 12:36:11 -0700 Subject: [PATCH 1/6] Add clarification on including additional context attributes Signed-off-by: cathyhongzhang --- spec.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/spec.md b/spec.md index 7e0a43013..1a8d80942 100644 --- a/spec.md +++ b/spec.md @@ -129,6 +129,19 @@ 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. From 48c45adab35adf558c0417effda655ef2bb3709e Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Tue, 11 Sep 2018 14:14:26 -0700 Subject: [PATCH 2/6] Incorporate Christoph's comment on duplication Signed-off-by: cathyhongzhang --- spec.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/spec.md b/spec.md index 1a8d80942..a6754654f 100644 --- a/spec.md +++ b/spec.md @@ -137,10 +137,10 @@ 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. +producer also adds 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 @@ -152,13 +152,8 @@ of a JSON serialization, the context attributes and the event data might both appear within the same JSON object. ### Extension Attributes -CloudEvent producers MAY include additional extension attributes within the -event. This enables event producers, or middleware, to include additional -metadata that might be used for any purpose in the processing of the -CloudEvent, such as identifying or correlating event sources. See -[CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) -for additional information concerning the use and definition of -extensions. +Any context attributes that are not defined in this specification are +extension attributes. This specification places no restriction on the type or semantics of the extension attributes. Each definition of an extensions SHOULD fully From 188397e8b301a0f102348ff817c92a4e345c97ba Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 12 Sep 2018 10:48:27 -0700 Subject: [PATCH 3/6] Update the PR per Christoph's comment Signed-off-by: cathyhongzhang --- spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index a6754654f..eab1f12f4 100644 --- a/spec.md +++ b/spec.md @@ -153,7 +153,9 @@ both appear within the same JSON object. ### Extension Attributes Any context attributes that are not defined in this specification are -extension attributes. +extension attributes. See +[CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) +for additional information concerning the use and definition of extensions. This specification places no restriction on the type or semantics of the extension attributes. Each definition of an extensions SHOULD fully From 9d3b9f12dcd30c27768ff59ffa723d3babe2598c Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Wed, 12 Sep 2018 15:32:16 -0700 Subject: [PATCH 4/6] move the paragraph to the "extension attributes" section Signed-off-by: cathyhongzhang --- spec.md | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/spec.md b/spec.md index eab1f12f4..2082a12b3 100644 --- a/spec.md +++ b/spec.md @@ -129,8 +129,18 @@ 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. +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. + +The choice of serialization mechanism will determine how the context +attributes and the event data will be materialized. For example, in the case +of a JSON serialization, the context attributes and the event data might +both appear within the same JSON object. + +### Extension Attributes +CloudEvents producers MAY include additional context attributes in the event +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 @@ -142,19 +152,7 @@ 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. - -The choice of serialization mechanism will determine how the context -attributes and the event data will be materialized. For example, in the case -of a JSON serialization, the context attributes and the event data might -both appear within the same JSON object. - -### Extension Attributes -Any context attributes that are not defined in this specification are -extension attributes. See -[CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) +See [CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) for additional information concerning the use and definition of extensions. This specification places no restriction on the type or semantics of the From 5feac503d9733d8a50b985a3f8d00c3fd31ff6fb Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Thu, 13 Sep 2018 12:28:19 -0700 Subject: [PATCH 5/6] Address comments in the meeting--move the section to the end of "Extension Attributes", and change "it is still suggested" to "SHOULD" Signed-off-by: cathyhongzhang --- spec.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/spec.md b/spec.md index 2082a12b3..f1fd05e99 100644 --- a/spec.md +++ b/spec.md @@ -141,17 +141,6 @@ both appear within the same JSON object. ### Extension Attributes CloudEvents producers MAY include additional context attributes in the event 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 also adds 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. - See [CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) for additional information concerning the use and definition of extensions. @@ -169,6 +158,18 @@ for extensions that might be of interest. Each specification that defines how to serialize a CloudEvent will define how extension attributes will appear. +Here is an example that illustrates the need for additional attributes. +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", the event producer SHOULD also 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 MAY also be used to +help intermediate gateways determine how to route the events. + ### eventType * Type: `String` * Description: Type of occurrence which has happened. Often this From 95bbe59114fbf0f0680e49656a634e3f9a9e61a8 Mon Sep 17 00:00:00 2001 From: cathyhongzhang Date: Thu, 13 Sep 2018 14:19:17 -0700 Subject: [PATCH 6/6] minor edit to change "MAY" to "can" Signed-off-by: cathyhongzhang --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index f1fd05e99..fb9154969 100644 --- a/spec.md +++ b/spec.md @@ -167,7 +167,7 @@ use to correlate this event with the other events. If such identity attributes happen to be part of the event "data", the event producer SHOULD also 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 MAY also be used to +and examine the event data. Such identity attributes can also be used to help intermediate gateways determine how to route the events. ### eventType