Protocol Versioning Summary
This chapter summarizes all version related aspects of the protocol definition.
Version of the Schema
The protocol definition <schema> has the version property, that specifies numeric version of the protocol.
<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" version="5">
...
</schema>
Version in the Interface
If protocol reports its version via transport framing or via some special "connection" message, and the protocol version must influence how some messages are deserialized / handled, then there is a need for <interface> definition, which must contain version field, marked as such using semanticType="version" property.
<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" version="5">
<interface name="Interface">
<int field="SomeName" type="uint16" semanticType="version" />
</interface>
...
</schema>
Version in the Frame
In addition to the <interface> containing version information, the transport <frame> is also expected to contain <value> layer, which will reassign the received version information to the message object (via <interface>).
<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" version="5">
<interface name="Interface">
<int field="SomeName" type="uint16" semanticType="version" />
</interface>
<frame name="Frame">
<size name="Size">
<int name="SizeField" type="uint16" serOffset="2"/>
</size>
<id name="Id">
<int name="IdField" type="uint8" />
</id>
<value name="Version" interfaces="Interface" interfaceFieldName="SomeName">
<int name="VersionField" type="uint16" />
</value>
<payload name="Data" />
</frame>
</schema>
Version of the Fields and Messages
Every message and field support the following properties, wich can be used to supply version related information.
sinceVersion - Version when the message / field has been introduced.
deprecated - Version when the message / field has been deprecated.
removed - Indication that deprecated message / field must be removed from
serialization and code generation.
Version Dependency of the Code
The generated code is expected to be version dependent (i.e. presence of some messages / fields is determined by the reported version value), if at least one of the defined <interface>-es contains version field (marked by semanticType="version").
If none of the interfaces has such field, then the generated code cannot be version dependent and all the version related properties become for documentation purposes only and cannot influence the presence of the messages / fields. In such cases the code generator is expected to receive required protocol version in its command line parameters and generate code for requested protocol version.
Compatibility Recommendation
In case CommsDSL is used to define new protocol developed from scratch and backward / forward compatibility of the protocol is a desired feature, then there are few simple rules below, following of which can insure such compatibility.
Last updated
Was this helpful?