Terminology additions for Source, Consumer, Producer and Intermediary

[deissnerk]

I added some definitions to the terminology section of the spec. I know there might be some discussion, especially regarding the producer. I need these terms to better propose rules of when and how the event context can be changed.

[duglin]

the term "data structure" sounds like it's implying the CloudEvent - if so, we should just say that. If not, can you elaborate on what you mean?

[duglin]

not sure what you mean by "content and data" - do you mean "context attribute and data attribute" ?

[duglin]

Or if you want to just say "Context" instead of "Context attributes" then perhaps make it a "C" instead of "c" and make it an href to the "Context" definition. It's not clear when you mean the CE Context entity vs something else.

[deissnerk]

Yes, that's a general issue about the terminology. If you look at the definition of event, it is already CloudEvent specific, explaining context and data. Does that mean that whenever I mention event, I imply that it is a CloudEvent?

[evankanderson]

This doesn't seem to address the questions about middleware, and middleware which modifies the context attributes, but all the content LGTM (non-voting).

[evankanderson]

Suggestion from the call: "an external producer"...

[erikerikson]

While I will accept the will of the group to accept this PR, this appears to contradict the definition of the source attribute as defined:

Description: This describes the event producer.

Given this, it seems that either the two should be disambiguated or this PR should be updated to change that text before it is merged.

However, the text following that first sentence and the given examples seem to imply different meaning and purpose.

[deissnerk]

Thanks for bringing this up. I was aware of this contradiction and wanted to stir up the discussion, because "describes the event producer" seems to me very vague. Why would we call a field, that describes the producer, source and not producer?
I think the fact the source attribute is a URI (an identifier and not descriptor) and the examples like urn:event:from:myapi/resource suggest that the source attribute identifies something more logical. I really have a hard time finding better words. Any proposals for a better wording are welcome.

[erikerikson]

I'm not sure I have terminology but perhaps its useful to consider that perhaps the "logical" source exists in user/application conceptual design space while producers live more in the space of system implementation? That seems the strongest argument for the #420 definition of source.

Perhaps a downside is that making it logical reduces the attribute's value to middleware or consumers. Personally, I had leaned towards preferring the source as a unique producer (guaranteed by application), primarily because of the relationship (assuming ordering guarantees) that ensures a map of producers to lists of ordered events which looks much like a logical clock if not a CRDT. If the IDs of producers are monotonically increasing and the event IDs are monotonically increasing, one also gets efficient and simple deduplication+idempotency which in my favored scenarios of many multi-versioned consumer groups makes the costs tractable. I think I, at least (if not fully), failed in my reading of the definition of source because the understanding I retained from some time ago, by bias, weighted that first sentence strongly and broadly ignored the implications of the remainder.

Given the approval of this PR then it seems that solution is to simply remove mention of producers from the definition of source.

[Tapppi]

Although we agreed that the terminology here makes sense on the call, writing a comment on PR #391 that made me realise this terminology is in conflict with both the name and description of the source attribute. Reading that comment should make one realise the confusion, but let me try to elaborate here. For clarity, I will capitalise the terminology introduced here.

According to this terminology, two instances of a "Users service" would be distinct PRODUCERS. Together they are a SOURCE (a logical system) and have distinct source attribute values compared to other SOURCES. However, the "Users service" as a SOURCE will likely produce events with multiple source attribute values for different subsystems/data/tables/etc within the system. When one says "source", it can be difficult to know whether they mean the SOURCE (e.g. "Users service") or a specific source attribute value from SOURCE (e.g. example.com/user/account or example.com/user/address).

The granularity of source attribute values will vary depending on system but that granularity would rarely match with SOURCE as defined here. For example a database change data capture system would probably base it on table/resource names/OIDs while an event-driven microservice would likely assign a value with semantic meaning not necessarily tied to technical implementation. Neither of these match SOURCE.

[duglin]

While we accepted this PR on today's call, based on some chats afterwards (and with @deissnerk's agreement) we decided to hold off merging it since there are still some lingering questions. Please add comments!!

[deissnerk]

@Tapppi I was actually quite happy that you brought this up, yesterday! So defining source as a logical system might not be the best wording. I still kind of like logical, though. I also liked that you mentioned semantic meaning.
Bottom line to me is that producer is something technical, while source is more logical or abstract, and with semantic meaning.
I could of course also delete my definition of source, as the attribute is already defined, but that would just shift the discussion, as my definition of producer would still be conflicting.
So I would like to know if any of the definitions in this PR make sense in your eyes, or if they should be adjusted. The discussion we had about #391 showed me that some more clarity on the definitions is needed.

[duglin]

We may need to do a little bit of word-merging with #391 in the "source" attribute section but that's minor and I think the two align nicely. LGTM

[duglin]

Approved on the 5/16 call

@deissnerk can you rebase this? Then I can merge it.

[deissnerk]

@duglin done

[duglin]

@deissnerk thanks!
merging