Add clarification for cloud events (#3417)

* add clarification for cloud events

Signed-off-by: yaron2 <schneider.yaron@live.com>

* update missing fields

Signed-off-by: yaron2 <schneider.yaron@live.com>

* Update daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md

Co-authored-by: Mark Fussell <markfussell@gmail.com>
Signed-off-by: Yaron Schneider <schneider.yaron@live.com>

* Update daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md

Co-authored-by: Mark Fussell <markfussell@gmail.com>
Signed-off-by: Yaron Schneider <schneider.yaron@live.com>

* add custom fields note

Signed-off-by: yaron2 <schneider.yaron@live.com>

---------

Signed-off-by: yaron2 <schneider.yaron@live.com>
Signed-off-by: Yaron Schneider <schneider.yaron@live.com>
Co-authored-by: Mark Fussell <markfussell@gmail.com>
Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>

daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md

@@ -11,39 +11,43 @@ To enable message routing and provide additional context with each message, Dapr
 Dapr uses CloudEvents to provide additional context to the event payload, enabling features like:
 
 - Tracing
-- Deduplication by message Id
 - Content-type for proper deserialization of event data
+- Verification of sender application
 
 ## CloudEvents example
 
-Dapr implements the following CloudEvents fields when creating a message topic.
+A publish operation to Dapr results in a cloud event envelope containing the following fields:
 
 - `id`
 - `source`
 - `specversion`
 - `type`
 - `traceparent`
+- `traceid`
+- `tracestate`
+- `topic`
+- `pubsubname`
 - `time`
 - `datacontenttype` (optional)
 
-The following example demonstrates an `orders` topic message sent by Dapr that includes a W3C `traceid` unique to the message, the `data` and the fields for the CloudEvent where the data content is serialized as JSON.
+The following example demonstrates a cloud event generated by Dapr for a publish operation to the `orders` topic that includes a W3C `traceid` unique to the message, the `data` and the fields for the CloudEvent where the data content is serialized as JSON.
 
 ```json
 {
-    "topic": "orders",
+  "topic": "orders",
-    "pubsubname": "order_pub_sub",
+  "pubsubname": "order_pub_sub",
-    "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01",
+  "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01",
-    "tracestate": "",
+  "tracestate": "",
-    "data": {
+  "data": {
     "orderId": 1
-    },
+  },
-    "id": "5929aaac-a5e2-4ca1-859c-edfe73f11565",
+  "id": "5929aaac-a5e2-4ca1-859c-edfe73f11565",
-    "specversion": "1.0",
+  "specversion": "1.0",
-    "datacontenttype": "application/json; charset=utf-8",
+  "datacontenttype": "application/json; charset=utf-8",
-    "source": "checkout",
+  "source": "checkout",
-    "type": "com.dapr.event.sent",
+  "type": "com.dapr.event.sent",
-    "time": "2020-09-23T06:23:21Z",
+  "time": "2020-09-23T06:23:21Z",
-    "traceparent": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01"
+  "traceparent": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01"
 }
 ```
 
@@ -65,6 +69,19 @@ As another example of a v1.0 CloudEvent, the following shows data as XML content
 ## Publish your own CloudEvent
 
 If you want to use your own CloudEvent, make sure to specify the [`datacontenttype`]({{< ref "pubsub-overview.md#setting-message-content-types" >}}) as `application/cloudevents+json`.
+If the CloudEvent that was authored by the app does not contain the [minimum required fields](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#required-attributes) in the CloudEvent specification, the message is rejected. Dapr adds the following fields to the CloudEvent if they are missing:
+
+- `time`
+- `traceid`
+- `traceparent`
+- `tracestate`
+- `topic`
+- `pubsubname`
+- `source`
+- `type`
+- `specversion`
+
+You can add additional fields to a custom CloudEvent that are not part of the official CloudEvent specification. Dapr will pass these fields as-is.
 
 ### Example
 
@@ -102,6 +119,10 @@ Invoke-RestMethod -Method Post -ContentType 'application/cloudevents+json' -Body
 
 {{< /tabs >}}
 
+## Event deduplication
+
+When using cloud events created by Dapr, the envelope contains an `id` field which can be used by the app to perform message deduplication. Dapr does not handle deduplication automatically. Dapr supports using message brokers that natively enable message deduplication.
+
 ## Next steps
 
 - Learn why you might [not want to use CloudEvents]({{< ref pubsub-raw.md >}})