> For the complete documentation index, see [llms.txt](https://alex-robenko.gitbook.io/commsdsl-specification/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alex-robenko.gitbook.io/commsdsl-specification/fields/common.md).

# Common Properties of Fields

Every field is different, and defines its own properties and/or other aspects. However, there are common properties, that are applicable to every field. They are summarized below.

## Name

Every field must define it's [name](/commsdsl-specification/names.md), which is expected to be used by a code generator when defining a relevant class. The name is defined using **name** [property](/commsdsl-specification/properties.md).

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <int name="SomeField" ... />
    </fields>
</schema>
```

## Description

It is possible to provide a description of the field about what it is and how it is expected to be used. This description is only for documentation purposes and may find it's way into the generated code as a comment for the generated class. The [property](/commsdsl-specification/properties.md) is **description**.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <int name="SomeField" type="uint8">
            <description>
                Some long
                multiline
                description
            </description>
        </int>
    </fields>
</schema>
```

## Reusing Other Fields

Sometimes two different fields are very similar, but differ in one particular aspect. **CommsDSL** allows copying all the properties from previously defined field (using **reuse** property) and change some of them after the copy. For example:

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <int name="SomeIntField" type="uint8" defaultValue="3" />
        <bitfield name="SomeBitfield>
            <int name="Member1" reuse="SomeIntField" bitLength="3" />
            <int name="Member2" type="uint8" defaultValue="10" bitLength="5" />
        </bitfield>
    </fields>
</schema>
```

In the example above member of the bitfield **Member1** copies all the properties from **SomeIntField** field, then overrides its **name** and adds **bitLength** one to specify its length in bits.

The **reuse** is allowed only from the field of the same **kind**. For example, it is **NOT** allowed for [\<enum>](/commsdsl-specification/fields/enum.md) field to reuse definition of [\<int>](/commsdsl-specification/fields/int.md), only other [\<enum>](/commsdsl-specification/fields/enum.md).

## Display Properties

**CommsDSL** supports generation of not only field's serialization and value access functionality, but also of various GUI protocol visualization, debugging and analysis tools. There are some allowed properties, that indicate how the field is expected to be displayed by such tools.

The **displayName** property is there to specify proper string of the field's name, with spaces, dots and other characters that are not allowed to exist in the [name](/commsdsl-specification/names.md).

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <int name="SomeIntField" displayName="Some Int Field" ... />
    </fields>
</schema>
```

If **displayName** is not specified, the code generator must use value of property **name** instead. In order to force empty **displayName**, use "\_" (underscore) value.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <int name="SomeIntField" displayName="_" ... />
    </fields>
</schema>
```

Sometimes the values of some fields may be controlled by other fields. In this case, it could be wise to disable manual update of such fields. To enable/disable such behavior use **displayReadOnly** property with [boolean](/commsdsl-specification/boolean.md) value.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <int name="SomeIntField" displayReadOnly="true" ... />
    </fields>
</schema>
```

Also sometimes it can be desirable to completely hide some field from being displayed in the protocol analysis GUI application. In this case use **displayHidden** property with [boolean](/commsdsl-specification/boolean.md) value.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <int name="SomeIntField" displayHidden="true" ... />
    </fields>
</schema>
```

## Versioning

**CommsDSL** allows providing an information in what version the field was added to a particular message, as well as in what version it was deprecated, and whether it was removed from being serialized after deprecation.

To specify the version in which field was introduced, use **sinceVersion** property. To specify the version in which the field was deprecated, use **deprecated** property. To specify whether the field was removed after being deprecated use **removed** property in addition to **deprecated**.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big" version="5" >
    <message name="SomeMessage" id="1">
        <int name="F1" type="uint16" />
        <int name="F2" type="int8" deprecated="5" />
        <int name="F3" type="uint8" sinceVersion="2" />
        <int name="F4" type="int32" sinceVersion="3" deprecated="4" removed="true" />
    </message>
</schema>
```

In the example above:

* **F1** was introduced in version **0** and hasn't been deprecated yet.
* **F2** was also introduced in version **0**, deprecated in version **5**, but **not**

  removed from being serialized.
* **F3** was introduced in version **2** and hasn't been deprecated yet.
* **F4** was introduced in version **3**, deprecated in removed in version **4**.

**NOTE**, that all the specified versions mustn't be greater that the version of the [schema](/commsdsl-specification/schema.md). Also value of **sinceVersion** must be **less** than value of **deprecated**.

The version information on the field in global **\<fields>** area or inside some [namespace](/commsdsl-specification/namespaces.md) does **NOT** make sense and should be ignored by the code generator. It is allowed when field is a member of a [\<message>](/commsdsl-specification/messages.md) or a [\<bundle>](/commsdsl-specification/fields/bundle.md) field.

## Failing Read of the Field on Invalid Value

Some fields may specify what values are considered to be valid, and there may be a need to fail the **read** operation in case the received value is invalid.

To achieve this **failOnInvalid** property with [boolean](/commsdsl-specification/boolean.md) value can be used. There are two main scenarios that may require usage of this property. One is the protocol being implemented requires such behavior in its specification. The second is when there are multiple forms of the same message which are differentiated by the value of some specific field in its payload. For example:

```
<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big" nonUniqueMsgIdAllowed="true" >
    <message name="Msg1Kind0" id="1" order="0">
        <int name="Kind" type="uint8" validValue="0" failOnInvalid="true" />
        ...
    </message>

    <message name="Msg1Kind1" id="1" order="1">
        <int name="Kind" type="uint8" defaultValue="1" validValue="1" failOnInvalid="true" />
        ...
    </message>

    <message name="Msg1Kind2" id="1" order="2">
        <int name="Kind" type="uint8" defaultValue="2" validValue="2" failOnInvalid="true" />
        ...
    </message>
</schema>
```

The example above defined 3 variants of the message with numeric ID equals to **1**. When new message with this ID comes in, the [framing](/commsdsl-specification/frames.md) code is expected to try reading all of the variants and choose one, on which **read** operation doesn't fail. The **order** property of the message specifies in what order the messages with the same ID must be read. It described in more detail in [Messages](/commsdsl-specification/messages.md) chapter.

## Pseudo Fields

Sometimes there may be a need to have "psuedo" fields, which are implemented using proper field abstration, and are handled as any other field, but not actually getting serialized when written (or deserialized when read). It can be achieved using **pseudo** property with [boolean](/commsdsl-specification/boolean.md) value.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big" version="5" >
    <message name="SomeMessage" id="1">
        <int name="SomePseudoField" type="uint16" defaultValue="0xabcd" pseudo="true" />
        <int name="SomeRealField" type="int8">
        ...
    </message>
</schema>
```

## Customizable Fields

The code generator is expected to allow some level of compile time customization of the generated code, such as choosing different data structures and/or adding/replacing some runtime logic. The code generator is also expected to provide command line options to choose required level of customization. Sometimes it may be required to allow generated field abstraction to be customizable regardless of the customization level requested from the code generator. **CommsDSL** provides **customizable** property with [boolean](/commsdsl-specification/boolean.md) value to force any field being customizable at compile time.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <string name="SomeField" customizable="true" />
    </fields>
</schema>
```

## Semantic Type

Sometimes code generator may generate a bit different (or better) code for fields that are used for some particular purpose. To specify such purpose use **semanticType** property.

Available semantic types are:

* **messageId** - Used to specify what type/field is used for holding numeric&#x20;

  message ID. Applicable to [\<enum>](/commsdsl-specification/fields/enum.md) fields.
* **version** - Used to specify that the field is used to hold protocol version.

  Applicable to [\<int>](/commsdsl-specification/fields/int.md) field (or [\<ref>](/commsdsl-specification/fields/ref.md) referening

  an [\<int>](/commsdsl-specification/fields/int.md)).
* **length** - Used to specify that the field holds total serialization length&#x20;

  of the subsequent fields. Applicable to [\<int>](/commsdsl-specification/fields/int.md) field&#x20;

  (or [\<ref>](/commsdsl-specification/fields/ref.md) referening an [\<int>](/commsdsl-specification/fields/int.md)).&#x20;

  The **length** semantic type makes sense only for&#x20;

  a member of [\<bundle>](/commsdsl-specification/fields/bundle.md) field and should be ignored in

  all other cases. The **length** semantic type

  was introduced in **v2.0** of **CommsDSL** specification.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <enum name="MsgId" type="uint8" semanticType="messageId" >
            <validValue name="Msg1" val="0x01" />
            <validValue name="Msg2" val="0x02" />
            <validValue name="Msg3" val="0x03" />
            ...
        </enum>
    </fields>
</schema>
```

Use [properties table](/commsdsl-specification/appendix/fields.md) for future references.