# Protocol Versioning Summary

This chapter summarizes all version related aspects of the protocol definition.

## Version of the Schema

The protocol definition [\<schema>](/commsdsl-specification/schema.md) has the **version** [property](/commsdsl-specification/properties.md), 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](/commsdsl-specification/frames.md) or via some special "connection" [message](/commsdsl-specification/messages.md), and the protocol version must influence how some messages are deserialized / handled, then there is a need for [\<interface>](/commsdsl-specification/interfaces.md) 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>](/commsdsl-specification/interfaces.md) containing version information, the transport [\<frame>](/commsdsl-specification/frames.md) is also expected to contain [\<value>](/commsdsl-specification/frames/value.md) layer, which will reassign the received version information to the message object (via [\<interface>](/commsdsl-specification/interfaces.md)).

```
<?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](/commsdsl-specification/messages.md) and [field](/commsdsl-specification/fields.md) 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>](/commsdsl-specification/interfaces.md)-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.

* Use [\<size>](/commsdsl-specification/frames/size.md) layer in the transport&#x20;

  [framing](/commsdsl-specification/frames.md) to report remaining length of the message.
* Use [\<value>](/commsdsl-specification/frames/value.md) layer to report protocol version

  in the transport [framing](/commsdsl-specification/frames.md) or define special "connect"&#x20;

  message that is sent to establish connection and report protocol version

  (mark the [\<value>](/commsdsl-specification/frames/value.md) layer to be **pseudo**).
* Always add new [fields](/commsdsl-specification/fields.md) at the end of the&#x20;

  [\<message>](/commsdsl-specification/messages.md). Don't forget to specify their

  version using **sinceVersion** property.
* Don't **remove** deprecated [fields](/commsdsl-specification/fields.md).
* Always add new [fields](/commsdsl-specification/fields.md) at the bottom of the

  [\<list>](/commsdsl-specification/fields/list.md) element.
* Add element serialization length report before every

  element of the [\<list>](/commsdsl-specification/fields/list.md) field (done using&#x20;

  **elemLengthPrefix** property).
* In case **elemFixedLength** [property](/commsdsl-specification/properties.md) is&#x20;

  assigned for the [\<list>](/commsdsl-specification/fields/list.md) (to avoid

  redundant report of the same element length before every element), never

  add variable length [fields](/commsdsl-specification/fields.md) to the element of the list.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alex-robenko.gitbook.io/commsdsl-specification/versioning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.