What is a CloudEvent property vs Event Data?

I’d like to gather our thoughts around a very important topic for our spec… what are the CloudEvents properties for? Or, what is CloudEvents itself for?

This has come up in relation to people starting to use CloudEvents and in particular when they are adding their own extensions to the serialization. We have a whole separate discussion going on around how to serialize extensions, but this issue is more about what type of data should be put into extensions at all.

While on the one hand we can’t stop any one from putting whatever they want into an extensions, we should at least provide some guidance as to how we, as spec authors, intended them to be used so that people are more likely to use the spec the way we intended, they’re then (hopefully) more likely to get the interop we’re hoping for, and are then less likely to break as we make changes to the spec in the future.

I think the high-order question I’m trying to ask is: when does data go into data and when does it go into a CloudEvents extension? And I think a related question is… what is the role of CloudEvents? Is it just something that’s used to move an event from one system to another or is it actually the event itself that is presented to the application and therefore the distinction between the CloudEvent properties and the data properties is blurred?

I’ve been assuming that CloudEvents was more about dealing with moving of events and that the “real” data that the application cares about is in data. Comparing this to an HTTP webapp, while there may be reasons why my app might go looking at the HTTP headers, that’s not the real purpose of its processing. Its real purpose is usually to process the HTTP body. So, in the CloudEvents case, I view adding application level data JUST to the CloudEvents properties as a mistake unless its being added just for routing purposes. For example https://github.com/cloudevents/spec/pull/225#issuecomment-401630707 mentioning “memoryLimitInMB” in a CloudEvents property (while technically legal from a spec perspective) isn’t really something we should be encouraging - that should be in data someplace.

But I’d really like to hear what other people think so we can prove some guidance to people on this topic in the primer.

[duglin]

The Primer includes this text:

---

CloudEvents, at its core, defines a set of metadata, called attributes, about the event being transferred between systems, and how those pieces of metadata should appear in that message. This metadata is meant to be the minimal set of information needed to route the request to the proper component and to facilitate proper processing of the event by that component. So, while this might mean that some of the application data of the event itself might be duplicated as part of the CloudEvent’s set of attributes, this is to be done solely for the purpose of proper delivery, and processing, of the message. Data that is not intended for that purpose should instead be placed within the event (the data attribute) itself.

---

I think that provides the clarity I was looking for so I’m going to propose that we close this issue. Please speak up if you think otherwise.

[duglin]

on the call today we agreed to close this issue - we can reopen if new info comes up.