Protocol versioning

Describes how a system of components supporting different versions of the protocol should work.

Why versioning?

Versioning of the information exchanged between bit repository components needs to be considered to avoid chaotic system behavior in case of component updates. If components in a bit repository system are based on different protocol version, a well defined strategy for handling this should include the ability to:

Avoid wrong interpretation of messages and data produced by a component built on a different version of the protocol.
Quickly detect and log that a different version has been received.
Create component resilient to communication with components based on different protocol versions.
Enable a degree of flexibility in which version of the protocol components in the same bit repository system are based on. This will enable minor protocol changes to be rolled out, without having to update all the system components. An example of this could be the adding of enum types, here only producers needing the new type and perhaps some of the consumers need to be updated. Another example is the addition of extra optional elements, where the components only need to be updated if the optional feature is required to be supported for that component.

Note that the integrity and robustness of the system is weighted higher than the ability to run a system with components based on different protocol versions.

Types of versioned entities

The following parts of the bit repository system are based directly on a protocol version and will therefore need to include information about which protocol version it is based on:

Protocol entities: Here we have two subtypes:
- Messages, exchange via. the message bus. Message are defined in the BitrepositoryMessages xsd.
- Data entities (exchanges through the file exchange protocol, http etc.). Data entities are defined in the BitrepositoryData xsd.
Bit repository components.

Messages and data entities are treated the same, so any reference to 'messages' in the rest of this page can be interchanged with 'data entities'.

Protocol version definition

A given protocol version consists of a number of version definitions, one for each operation type. An operation version consists of a Version and a minVersion element, see the section on 'Minimal version information' for details. The value of the Version element will normally correspond to the protocol version.

Versioning mechanisms

The following mechanisms are used to leverage the abilities listed in the above section.

Use schema validation

The usage of a well-defined (xsd based) syntax which should be used to validate all received messages will ensure that messages in older or newer formats will only be accepted if the message only contain elements adhering to the component's native protocol version.

This solution will leverage bullets 1,2 and 4 in the 'Why versioning' list.

Include protocol version in message and components

All messages must include the version number the producing component was based on. All components must also be aware of the protocol version they were based on.

This will ensure that the bullet 2 feature can be implemented in message receivers.

Minimal version information

Besides the check on whether a received message conforms to the syntax defined in the protocol schema we also need to ensure semantic changes (the meaning of a element has changed) can be detected and handled. To detect this situation we have introduced a minimal version attribute which needs to be included in all messages. The minVersion in a message indicates the first version of the protocol which had a semantic meaning consistent with the message version. This also means protocol version prior to a messages minVersion used a semantic inconsistent with the message semantics.

The result is that components should only attempt to handle messages where:

Message protocol Version >= Component protocol minVersion for the given operation
Message protocol minVersion <= Component protocol Version for the given operation

Include versioning information for the individual message types

The version information for the individual message types are distributed together with the protocol xsd's themself. The versioning specification is located in the versioning folder. The versioning definition is modeled as a default protocol version and minimal version, which can be overridden by special configuration for specific messages or data entities.