It is highly recommended that Companion Specifications do not have breaking changes in new versions. There are strategies that can be used to avoid breaking changes:
- Create subtypes and add mandatory elements to the subtypes. Create new conformance units and profiles requiring the use of the subtypes. This approach only works to add new mandatory things, and is a compatible change, such that an old client works with a new server. A new client can be designed to also accept the old types, or it may not work with old servers. That is a decision of the client developer. Note that depending on what type gets subtyped by a new version, many other types using this type may need to be changed as well.
- Add optional components to existing types and make them mandatory by conformance units and profiles. This avoids creating subtypes which might require creating other subtypes, etc. Otherwise, the same logic as for approach 1 applies. Old clients will work with new servers, and new clients may work with old servers if they do not require the new mandatory things.
When it cannot be avoided to break something from an existing specification in a new version, there are different options:
- Create a new Namespace and thus define, conceptionally, a completely new information model. It is recommended to change the NamespaceUri and add a version number at the end (for example, V2 at the end for the second version). This is on one hand the cleanest solution; on the other hand, this is a completely incompatible change of the model. No old client will directly work with a new server and vice versa.
- Create new types independent of the old when needed, e.g. DeviceType2 for DeviceType. This allows also to remove mandatory things, that have been proven to be problematic. Depending on how many types have been changed, old clients may or may not be able to do reasonable things with new servers. If old servers should be supported, new clients have to be designed to support both types. Note that depending on what type gets exchanged by a new version, many other types using this type need to be changed as well.