XML-based Dictionary Description

XML-based dictionary description allows specifying a customized dictionary of a FIX messaging specification. Its format is described by the corresponding XML schema.

Adding New Field

To add a new field to a FIX Message add the corresponding <Field> entity.

For example:

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">

    <FIX version="4.0">
        <Message type="D">
            <!-- Field #526 does not belong to the Standard FIX 4.0. -->
            <Field tag="526" name="SecondaryClOrdID" isRequired="true"/>

            <!-- Field #21 is required in Standard FIX 4.0, but will be optional in this FIX Dictionary. -->
            <Field tag="21" name="HandlInst" isRequired="false"/>
        </Message>
    </FIX>
</Dialect>

Note

Adding a <Field> element for the already registered (e.g., standard) field or group causes the Engine to override its attribute. This allows modifying attributes of an existing field. For example, this allows making a mandatory field an optional one, and vice versa. The same approach could be used to replace existing FIX repeating groups with regular fields, and vice versa.

Adding New Repeating Group

To add a new repeating group to a FIX message, add the corresponding <Group> entity. The same approach is used to add new fields to an existing repeating group.

For example:

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">

    <FIX version="4.0">
        <Message type="D">
            <!-- Repeating group for pre-trade allocation (does not belong to the Standard FIX 4.0). -->
            <Group numberOfInstancesTag="78" name="NoAllocs">
                <Field tag="79" name="AllocAccount"/>
                <Field tag="661" name="AllocAcctIDSource"/>
                <Field tag="736" name="AllocSettlCurrency"/>
                <!-- Other group fields go here. -->
            </Group>
        </Message>
    </FIX>
</Dialect>

Note

In the case of a new group definition, the first field will be used as a leading tag (the tag which separates repeating groups entries). If the definition describes changes to an existing group, then the original leading tag remains in force.

Adding New Message

To define a custom (user-defined) message, add the corresponding <Message> entity.

For example:

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">

    <FIX version="4.2">
        <Message type="UserDefinedMessage_1">
            <Field tag="100" isRequired="true"/>
            <Field tag="101"/>
        </Message>
    </FIX>
</Dialect>

This user-defined message can be used in precisely the same way as a standard FIX Message.

For example:

var customMessage = new Message("UserDefinedMessage_1", ProtocolVersion.Fix42);

customMessage.Set(100, "Field 100")
             .Set(101, "Field 101");

customMessage.Validate();

Console.WriteLine($"Custom message: {customMessage}");

Note

The Engine allows to send and receive unknown messages via the ValidateUnknownMessages configuration property. However, defining custom messages using the dictionary definition have important benefits:

• The Engine does not differentiate between messages that are defined using custom FIX dictionary from messages that are defined by the FIX Protocol. This gives the opportunity to use strict message validation to check the validity of incoming and outgoing messages.
• Using a custom dictionary allows adding custom messages of the same complexity as messages that are defined by the Standard. This includes messages with repeating groups of any nesting level.

Removing Fields, Repeating Groups or Messages

The presence of a field definition in the dictionary description overrides the entity of the same tag number.

However, sometimes it is needed to remove specific fields, repeating groups, or messages completely.

The dictionary description syntax has the "mode" attribute that allows the removal of a single field, repeating group or an entire message from the dictionary. The "remove" value must be specified for the attribute in the corresponding <Field>, <Group>, or <Message> entity.

For example:

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">

    <FIX version="4.0">

        <Message type="8">
            <!-- Partial fill not supported, order is either
                         filled or canceled. So CumQty is not needed. -->
            <Field tag="14" name="" mode="remove"/>

            <!-- No need in the MiscFees group as well. -->
            <Group numberOfInstancesTag="136" name="MiscFees" mode="remove"/>
        </Message>

        <!-- "New Order - List" is not supported. -->
        <Message type="E" mode="remove"/>

    </FIX>
</Dialect>

Overriding Standard Dictionary

Using the "mode" attribute the FIX standard dictionary can be overridden.

If the "override" mode is defined for the FIX version, FIX Engine will replace the entire definition of this version with the new one.

For example, the description of FIX version 5.0 below will be empty and not contain any definitions at all.

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">

    <FIX version="5.0" mode="override"/>

</Dialect>

Overriding Messages or Repeating Groups

When the "override" mode is defined for either a message or a repeating group, the message or repeating group will consist only of the fields and nested repeating groups specified by the description.

<?xml version="1.0" encoding="utf-8"?>

<Dialect xmlns="https://ref.onixs.biz/fix/dialects"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">

    <FIX version="4.4" id="OverrideQuote">
        <Message type="S" name="Quote" mode="override">
            <Field name="OrderQty" tag="38" type="QTY"/>
            <Field name="CashOrderQty" tag="152" type="QTY"/>
        </Message>
    </FIX>

</Dialect>

Note

Once a repeating group is overridden, its leading tag will be changed in the same way as if it is a new group definition, i.e., the first field, defined within the overridden group, will be considered as the leading one.

Note

Message overriding impacts the basic message structure. Only the following session-level fields will always be present in the overridden message structure:

• BeginString (8)
• BodyLength (9)
• MsgType (35)
• SenderCompID (49)
• TargetCompID (56)
• MsgSeqNum (34)
• PossDupFlag (43)
• CheckSum (10)

All other fields (including optional session-level ones) should be added to the overridden message structure.

Controlling Field Order

To control field order, create a custom dictionary and describe all fields in a message or repeating group in the necessary order using the "override" mode.

For example:

<?xml version="1.0" encoding="utf-8"?>
<Dialect
                xmlns="https://ref.onixs.biz/fix/dialects"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2_18.xsd">

    <FIX version="4.4">

        <!-- Now the Advertisement message contains only one Text field -->
        <Message type="7" mode="override">
            <Field tag="58" name="Text" isRequired="true"/>
        </Message>

        <Message type="S">
            <!-- Completely redefine the NoLegs group to not use the Legs component -->
            <Group numberOfInstancesTag="555" name="NoLegs" mode="override">
                <!-- Now tag # 588 will be the leading tag in the group. -->
                <Field tag="588" name="LegSettlDate"/>
                <Field tag="8000"/>
            </Group>
        </Message>

    </FIX>
</Dialect>

Components

The <Component> entity allows describing field collections to reuse them later. It can contain <Field> , <Group> or other <Component> entities.

The "name" attribute identifies the component.

When a <Component> entity occurs in a message description, all fields from this component are treated as fields directly described in this message.

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">

    <FIX version="4.2">

        <!-- Header component description. -->
        <Component name="Header">
            <Field tag="8" name="BeginString" isRequired="true" />
            <Field tag="9" name="BodyLength" isRequired="true" />
            <Field tag="35" name="MsgType" isRequired="true" />
            <Field tag="49" name="SenderCompID" isRequired="true" />
            <Field tag="56" name="TargetCompID" isRequired="true" />
            <Field tag="115" name="OnBehalfOfCompID" />
            <Field tag="128" name="DeliverToCompID" />
            <Field tag="90" name="SecureDataLen" />
            <Field tag="91" name="SecureData" />
            <Field tag="34" name="MsgSeqNum" isRequired="true" />
            <Field tag="50" name="SenderSubID" />
            <Field tag="57" name="TargetSubID" />
            <Field tag="116" name="OnBehalfOfSubID" />
            <Field tag="129" name="DeliverToSubID" />
            <Field tag="43" name="PossDupFlag" />
            <Field tag="97" name="PossResend" />
            <Field tag="52" name="SendingTime" isRequired="true" />
            <Field tag="122" name="OrigSendingTime" />
        </Component>

        <!-- Trailer component description. -->
        <Component name="Trailer">
            <Field tag="93" name="SignatureLength" />
            <Field tag="89" name="Signature" />
            <Field tag="10" name="CheckSum" isRequired="true" />
        </Component>

        <Message type="A" mode="override">
            <!-- Using fields from the Header component. -->
            <Component name="Header" />
            <Field tag="98" name="EncryptMethod" isRequired="true" />
            <Field tag="108" name="HeartBtInt" isRequired="true" />
            <Field tag="95" name="RawDataLength" />
            <Field tag="96" name="RawData" />
            <!-- Using fields from the Trailer component. -->
            <Component name="Trailer" />
        </Message>
    </FIX>
</Dialect>

Types

The <Type> entity allows describing a list of valid field values. It can contain <Value> entities.

The "name" attribute identifies the type.

The "mode" attribute allows to append new values to the type or replace the entire definition if override mode is specified.

The "base" attribute identifies the base type for the enumeration, which can be string (default), int or char.

The <Value> entity has enum and description attributes.

<?xml version="1.0" encoding="utf-8"?>
<Dialect xmlns="https://ref.onixs.biz/fix/dialects"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">
  <FIX version="5.0">
    <Type name="UserDefined" mode="append">
        <Value enum="4" description="enum description 4"/>
        <Value enum="5" description="enum description 5"/>
    </Type>
    <Message type="D">
      <Field tag="21" name="HandlInst" type="UserDefined"/>
    </Message>
  </FIX>
</Dialect>

Sample XML-based Dictionary Description File

Example of a FIX Dictionary description file:

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">

    <FIX version="4.3">

        <Message type="W">
            <!-- Make the required field an option one. -->
            <Field tag="64" name="FutSettDate"/>
        </Message>

        <Message type="y">
            <Group numberOfInstancesTag="146" name="NoRelatedSym">
                <!-- Add a new field to the existing repeating group. -->
                <Field tag="64" isRequired="true" name="FutSettDate"/>
            </Group>
        </Message>

    </FIX>

    <!-- Session-level dictionary -->
    <FIX version="4.3" id="ForTradeWithNewXMessage">

        <Message type="X">
            <Field tag="55" name="Symbol"/>
            <Field tag="64" name="FutSettDate"/>
        </Message>

    </FIX>

    <!-- Dictionary for simplified trading. -->
    <FIX version="4.0">

        <!-- All orders are of market type. -->
        <Message type="D" mode="override">
            <Field tag="54" name="Side" isRequired="true"/>
            <Field tag="55" name="Symbol" isRequired="true"/>
            <Field tag="53" name="Quantity" isRequired="true"/>
        </Message>

        <!-- "New Order - List" is not supported. -->
        <Message type="E" mode="remove"/>

        <!-- "Partial fill" is not supported. -->
        <Message type="8">
            <Field tag="14" mode="remove"/>
        </Message>

    </FIX>

</Dialect>