Compatibility guidelines for event type versions?

[deissnerk]

There are some cases in which event type versions might play an important role.
E.g.:

1. If a standardized event type, that was defined by another organization, is used, it is important for the producer to add the version, as changes in a new version of the event type are not in the producer's hand.

2. If a consumer needs some information that is only available in an event type starting with version x, it might make sense to subscribe to events of the type with version >= x.

Right now the event type version is optional and just a string. So version ranges are not possible. It is also not clear, if a version is a super set of an older one or completely incompatible. I think that adhering to a versioning spec like Semantic Versioning might bring some advantages for interoperability use cases.

I could come up with an according PR, but would like to get some opinions first. Should the event-type-version remain as it is? Should there be just some recommendations or even binding rules in the spec?

Assigned to: @deissnerk

[deissnerk]

@duglin You can assign this to me.
@inlined This is the issue about event type versioning which I referred to when we were talking at KubeCon.

[duglin]

I wonder if it wouldn't be easier to just merge EventType and EventTypeVersion into one string. Then let the author of that string decide how/if/when to version it. We could add text "recommending" that the string be versioned, but ultimately its up to the entity defining it.

As a reference point. during the demo work I asked @clemensv how MSFT's Event Grid had people specify that they wanted CloudEvents as the output format - and he said that they specified something along the lines of "cloudeventv01schema" as the output type. So, that pattern seems to make sense to me - and it makes our life easier.

[duglin]

Related: #33

[inlined]

@deissnerk thanks for the bump!

@duglin Honestly I'm in favor of dropping on EventTypeVersion and just using the data schema. I think eventTypeVersion can lead to a lot of confusion.

Imagine Twitter makes their API eventful and then creates an API v2. When I subscribe for the com.twitter.tweet.publish event, I probably want all tweets regardless of which client wrote to that tweet. Instead, I'd want to subscribe to the com.twitter.tweet.publish event and dictate the my client knows how to handle the schema from v1 only.

[duglin]

yep - between someone having the option of making the EventType string anything they want (w/ or w/o a version part) and the data schema and content-type it sure seems to me like they have enough ways to express what they want.

[deissnerk]

@inlined

Instead, I'd want to subscribe to the com.twitter.tweet.publish event and dictate the my client knows how to handle the schema from v1 only.

I see your point. But is this just about the version? Isn't there a general overlap between schemaURL and eventType?
Isn't the eventType(Version) only referring to more than the data schema of the event? It has previously been mentioned that the eventType is also providing context to the other context attributes.
In #169 @clemensv wrote:

the URI is unambiguous in the context of the namespaced eventType. If there is a common event type, that event type would also define the URI shape. I think of event types as actual types that lay down the law for the shape of the event, not mere labels.

So versioning the schema and the event type may not be the same thing.

Btw: If you make the version part of the schemaURL, you can only filter on equality. Of course you could make the version a query parameter of schemaURL, but that would be a convention and not spec.

[duglin]

@deissnerk any update on this one?

[deissnerk]

@duglin Sorry, not yet. To be honest, I am a bit confused by the overlap between event type and schemaURL (see above). I'd like to see a few more opinions here.

[inlined]

Btw: If you make the version part of the schemaURL, you can only filter on equality.

I may be apocryphal here, but I'm fine with this. I can't honestly think of a business that uses more than major version numbers for their API. Within a version backwards compatible features can be added and across major versions it doesn't make sense to expect an ordering.

I generally thought of these as something that the event registration would negotiate for the source and action. Are you expecting a use case where an action gets several different formats of the same event data?

[deissnerk]

Seems that in #172 some related points were brought up by @scothis.
While I understand that eventType and eventTypeVersion have a different scope than schemaURL, I'm still looking for a good example to illustrate the difference. How does the eventType(Version) influence the way the other context attributes are used?
@clemensv What do you think?

[duglin]

During 6/15 f2f, we agreed to:

• Proposal: remove eventTypeVersion and just use schemaURL
• AI Klaus: to write-up a PR