Discuss the versioning in event structure

[tanjadegroot]

Problem description
The event type field carries a version number:
e.g. "$.type" is set to "org.camaraproject.qod-provisioning.v0.status-changed.
In some cases, there is a v1 API that uses an event.type with v0 in it.

Possible evolution
This item is to discuss if versioning guidelines should be create (based on cloudevent ones if existing), for usage in the CAMARA context.
It is also to understand if there is a relationship with he API version or not.

Considering the example type in the Commonalities artefact () one could also drop the version altogether as the OAS file containing it already has a version field.
type:
type: string
description: 'type of event as defined in each CAMARA API (e.g.: org.camaraproject.qod.qos-status-changed-event)'
example: 'org.camaraproject.qod.qos-status-changed-event'
minLength: 25

NOTE: maybe this is a discussion for Commonalities rather than RM, and maybe it was discussed already there.

A related arftefact is https://github.com/camaraproject/Commonalities/blob/main/artifacts/camara-cloudevents/event-subscription-template.yaml

It states:
Note on event name convention: the event type name MUST follow: org.camaraproject.<api-name>.<api-version>.<event-name>

[eric-murray]

Hi @tanjadegroot

I think this is a versioning, and hence a release management, issue.

My initial view:

• "Stable" APIs should use "stable" event types (i.e. version number > 0), but the two version numbers do not need to be synchronised. So a "v2" API can still use "v1" events if the event structure is unchanged. If the event structure is changed, the version number must be updated. Whether the API itself then needs a major or minor version bump will depend upon the exact change.
• All "v0" APIs should use "v0" event types, even if the event definition is changed - sematic versioning means anything can change at any time, so clients for an updated "v0" should always read the documentation anyway.

[tanjadegroot]

Thanks Eric.
In the mean time I found a guideline in the template (https://github.com/camaraproject/Commonalities/blob/main/artifacts/camara-cloudevents/event-subscription-template.yaml) that states:
Note on event name convention: the event type name MUST follow: org.camaraproject...

an OK, we'll keep this as a release mgmt issue then.