Nested vs top-level properties

[cloudevents]

Nested vs top-level properties

[schatekar]

I may be wrong but I feel it is too early to decide either way. There are some standard HTTP headers that allow packing of multiple values of different kinds into a single header entry. A similar approach can be taken for some of the context variables.

IMO, the spec should focus on defining the universal structure/share of an event. How this event then gets transported over HTTP (or some other transport protocol) can become a topic of adopting the spec for that transport. I am not suggesting that "adopting CloudEvents for HTTP" becomes a spec in itself but having the two defined separately gives us the freedom to optimise both independently of each other.

[yaronha]

The reason for the "flat" approach is to allow mapping to protocols w Headers (like HTTP, AMQP, ..) and avoid extra serialization

[austencollins]

With the right naming convention, could we support both? It would be nice to have nested properties in JSON serialization, since having everything on the parent level can be hard to read. However, if they can also be flattened to include in headers that are sensible, that would be optimal.

[duglin]

Closing since this is either already covered by what's in our docs or if not will automatically happen as we add new attributes.

[bruth]

I know the spec has evolved since this issue was opened, but I am curious if there are any new thoughts regarding nested. I understand the argument for the core attributes to be top-level, however extensions in particular are awkward to have as top-level keys.

The main argument is that they can clash with any new attribute introduced in the spec. Introducing an extensions or exts map could be the container for adding extension attributes.

This is similar to how HTTP headers prefixed with X-* are considered non-standard. For example the HTTP binary mode could encode extensions as Ce-X-*. Or there could be a declaration that if extensions are used, the structured mode must be used.

Another side effect of this, is that for strongly typed formats/languages, it prevents the need to generalize the top-level event type as a map<string, Any>. Now only the extensions map would be generalized. I point out the protobuf format in particular as an example:

// allows a map to appear inside `oneof`
message CloudEventMap {
  map<string, CloudEventAny> value = 1;
}

message CloudEventAny {
  oneof value {
    string string_value = 1;
    bytes binary_value = 2;
    uint32 int_value = 3;
    CloudEventMap map_value = 4;
  }
}

Which doesn't save on not having to serialize the top-level keys and makes it a bit awkward to work with. If extensions were a separate map, then we could have a top-level message like:

message CloudEvent {
  // The version of the CloudEvents specification which the event uses.
  string specversion = 1;

  // Identifies the context in which an event happened.
  string source = 2;

  // Identifies the event.
  // Producers MUST ensure that source + id is unique for each distinct event.
  string id = 3;

  // Type of occurrence which has happened.
  string type = 4;

  // Content type of the data attribute value.
  string datacontenttype = 5;

  // Describes the content encoding for the data attribute when the data field
  // is encoded as a string.
  string datacontentencoding = 6;

  // A link to the schema that the data attribute adheres to.
  string schemaurl = 7;

  // Describes the subject of the event in the context of the producer (identified by source).
  string subject = 8;

  // The event payload.
  CloudEventAny data = 9;

  // Extensions.
  map<string, CloudEventAny> extensions = 10;
}

[bruth]

☝️Sorry, just read this and most of my points are acknowledged. The main argument seems to be around the optionality of new attributes, if introduced, and the promotion of extensions to core attributes. Since everything is centered around bumping the spec version, consumers should rely on that to determine how to handle the message.

the authors decided that having two different locations within an incoming event for unknown properties could lead to interoperability issues and confusion for developers.

One concern with this claim is that what if I define an extension with its own type/semantics that has the same name as one that gets promoted? Since they are both top-level, they would clash. However if I define my in extensions then even if one gets promoted, I can still rely on the one in extensions. I realize this is an edge case and its probably best to namespace the extension attributes, but just calling it out.

[duglin]

Yep - IMO unless you're defining a property that you really want to be general purpose (in which case you should approach the spec authors with the idea) you should namespace your extension.