Skip to content
Events Service

Versioning

Events have three levels of versioning:

  • Cloud Events Spec version: The version of the Cloud Events Spec, to which the event adheres. This should change VERY rarely, and should never need to be queried.
  • Major version: This corresponds to entirely different versions of events. Events must have major version changes when there are breaking changes to schemas.
  • Data schema version: This corresponds to the version of the data schema of an event for non-breaking changes. This is the same as a minor version of the software.

Publishers have the flexibility to make spec updates without introducing new versions, however they it’s their responsibility to guarantee that modifications do not disrupt or break consumers.

Cloud events spec version

A spec version indicates the CloudEvents spec version used by the event. Each payload identifies this as the specversion. The spec version will never change without the Major Version changing. In general, the CloudEvents Spec Version changes very rarely, and the Events Service will never require existing events to up-version the CloudEvents Spec. For more information, see cloudevents.io{:target=“_blank”}.

Major version

Major versioning denotes significant breaking changes to an event. When an event version changes at the top level, existing subscriptions are unaffected. Consumers must create a new subscription to the updated event version to receive events of the latest version. All version references in the SDK and the rest endpoints correspond to the top-level version.

Publisher expectations

Publishers are expected to adequately document major version changes in the spec and introduction documentation. As a general practice, the old version of the event should be maintained for a minimum of 6 months (unless the old version exposes security vulnerabilities); this allows integrators ample time to create a new subscription to the updated version.

Subscriber expectations

If a new major version is made available, each subscriber must create a new subscription to the updated major version. Suppose the publisher requests that the old version be depreciated; in that case, existing subscribers are given an appropriate time to create a new subscription to the new major version before the old version is shut down.

Data schema version

In Events, the data schema is versioned. The publisher of an event can increment the version of their data schema when the schema changes. This versioning is intended for minor/non-breaking changes. Each message payload contains a URL pointing users to the correct data schema in the appropriate version. Consumers of the event will receive events in the new data schema version for their existing subscriptions.

Publisher expectations

To prevent breaking changes for consumers, producers should not edit or delete existing fields; fields may only be added when versioning the data schema. Introduction Documentation and the example section within the schema should be updated accordingly. To create a consistent paradigm for consumers, the data schema version should reset when a major version occurs (regardless of the Data Schema version, it should reset to 1.0 when a major version occurs).

Subscriber expectations

All Data Schema Versioning should not require integrators to make any changes to their polling of the Events Service. Each event contains a URL to the event schema with parsing instructions, and this is how producers can update the Data Schema Version without updating the major version.

Example payload for the Profiles V2.0 event, note that the major version is not indicated in the payload.

"payload": {
     "datacontenttype": "text/json",
     "Data":        "{trn:trn:profilesdev:accounts:STRING,caller:trn:profilesdev:applications: STRING,application: trn:profilesdev:applications:STRING,targetTrn:, relationName:,propertyKeys: [name,type]}",
     "subject": "trn:profilesdev:space:global",
     "specversion": "1.0",
     "id": "rrt-0a7266df4a0595db5-c-wo-25502-61373414-1",
     "source": "/profiles.dev/108afd70-34ab/name",
     "time": "2022-03-03T05: 32: 02Z",
     "type": "create",
     "dataschema": "https://cloud.stage.api.trimblecloud.com/events/registry/1.0/content/schematype/data/namespaces/com.trimble.tcp.profiles/events/profiles/v1.0"
}