FIX and FIXML Dictionaries Customization Guide
This article describes how to customize FIX and FIXML dictionaries
The articles describe:
- how FIX and FIXML dictionaries are built,
- how to customize dictionaries:
- how to define a custom tag;
- how to extend existing message with a custom tag;
- how to extend the list of custom tag values;
- how to define a custom message etc.
When you are applying customizations for FIX and FIXML dictionaries to build a custom FIX FIXML converter make sure that both dictionaries fully correspond to each other.
How to customize a FIX dictionary
In order to apply any customizations for a standard FIX Dictionary it is necessary to do the following:
- Refer to fixdic.xml
- Apply changes
- Store changes to the file
Fixdic.xml structure
FIX dictionary consists of the following blocks:
Block name | Description | |
|---|---|---|
| <fixdic> | FIX dictionary main node | |
| <typelist> | Data types list definition | |
| -> | <typedef > | Data type definition |
| <fielddic> | FIX tags and values identifier | |
| -> | <valblockdef> | FIX tag values block definition |
| -> | <fielddef> | FIX tag definition |
| <msgdic> | Messages and component blocks definition | |
| -> | <blockdef> | Definition of the Component Block used in FIX message |
| -> | <msgdef> | FIX message definition |
An example of FIXdic.xml structure is given below.
Examples of different customizations
How to add a custom value to the existing FIX tag
Example 1: Valid values for AllocRejCode (88) tag should be extended with custom value "14” (unknown clearing account).
Definition: AllocRejCode (88) tag is defined in the following way:
According to this definition, it is necessary to refer to FIX tags values blocks named “AllocRejCode” and specify the following (refer to text marked bold dark blue)
Example 2: Valid values for MDEntryType (269) tag should be extended with custom value “R” (Rolling average).
Definition: Find MDEntryType (269) tag definition in the file and add the value as illustrated in the example below:
<fielddic>
<!-- ... -->
<fielddef tag="269" name="MDEntryType" type="char">
<!-- ... -->
<item val="R">Rolling average</item>
</fielddef>
<!-- ... -->
</fielddic>
How to change ‘required’ attribute of a tag in FIX message
Example: It is necessary to change the „required‟ attribute for Password (554) tag from „not required‟ to „required‟ in FIX message User Request (MsgType = „BE‟)
Definition: Refer to <msgdic> section and find User Request (MsgType = „BE‟) message definition. Find Password (554) tag definition in message definition and add the following attribute (if absent) req = “Y” (refer to marked bold dark blue).
How to change ‘required’ attribute of a tag in component block
Example: It is necessary to change the „required‟ attribute for Commission (12) and Commission Type (13) tags from „not required‟ to „required‟ in Commission Data component block.
Definition: Refer to <msgdic> section and find Commission Data component block definition. Define the following attribute (if absent) req = “Y” in component block Commission (12) and Commission Type (13) tags (refer to marked bold dark blue).
If the tag was defined as „not required‟ via req = “N” attribute, its value should be changed to “Y”.
How to change ‘required’ attribute of a component block in FIX message
Example: It is necessary to change „required‟ attribute in Settlement Instruction Request (MsgType = „AV‟) message for “Parties” component block from „not required‟ to „required‟.
Definition: Refer to <msgdic> section and find Settlement Instruction Request (MsgType = „AV‟) message definition. Find “Parties” component block definition in message definition and add the following attribute (if absent) req = “Y” (refer to marked bold dark blue).
The same can be done if it is necessary to change the „required‟ attribute for tag inside a repeating group.
How to add a custom tag to the existing FIX message
Example 1: It is necessary to add a custom tag PolicyCode (8060) as the "not required" field in New Order Single (MsgType = "D") message. The tag has no predefined valid values; the data type for values is String.
Definition:
1. Declare a custom FIX tag in the fields dictionary (<fielddic> section). Define the new field parameters within <fielddef> declaration as below:
<fielddic>
<!-- ... -->
<fielddef tag="8060" name="PolicyCode" type="String">
<descr>
<p>Policy cide description</p>
</descr>
</fielddef>
<!-- ... -->
</fielddic>
<descr> contains tag description, it is not required and can be omitted
2. Inside <msgdic> section find the message definition (<msgdef> section) for New Order Single (MsgType = "D") add PolicyCode (8060) field description near the other fields:
<msgdic>
<!-- ... -->
<msgdef msgtype="D" name="New Order - Single">
<!-- ... -->
<field tag="8060" name="PolicyCode">
</msgdef>
<!-- ... -->
</msgdic>
Example 2: It is necessary to add a custom tag VTRejectReasonBid (8100) as a required field in Mass Quote Acknowledgement (MsgType = "b") message. The tag has the following predefined valid values:
- “0” – Exchange option
- “1” – Unknown or non-tradable contract
- “2” – Exchange closed
- “99” – Other
Definition:
1. Declare a custom FIX tag in fields dictionary. Refer to <fielddic> section and define the following
2. Refer to <msgdic> and find Mass Quote Acknowledgement (MsgType = „b‟) message description and add VTRejectReasonBid (8100) as described below in bold dark blue:
How to add a custom tag to the existing FIX component block
Example: It is necessary to add a custom tag ShareTier (8800) as not a required field in the „Commission‟ component block. The tag has the following predefined valid values: „A‟, „B‟, „C‟; the data type for values is char.
Definition:
1. Declare a custom FIX tag in the fields dictionary. Refer to <fielddic> section and define the following
<descr> contains tag description, it is not required and can be omitted.
2. Refer to <msgdic>, find „Commission‟ component block description, and add ShareTier (8800) as described below in bold dark blue:
How to add custom repeating group to the existing FIX message
Example: It is necessary to add a custom repeating group in List Execute (MsgType = „L‟) message. The repeating group consists of the following fields:
- leading tag: NoTradingSessions (386)
- repeating group fields:
- start field: TradingSessionID (336)
- other fields: TradingSessionSubID (625)
The repeating group is not required in the message.
Definition: Refer to <msgdic>, find List Execute (MsgType = „L‟) message description, and add a repeating group as described below in bold dark blue:
The custom repeating group can be added to the component block or into another repeating group in the same way.
How to add a custom FIX message
Example: It is necessary to add a custom Start One Side Only Period Confirmation (MsgType = „U0505‟) message. The message consists of the following fields:
- ClOrdID (11) – required
- Side (54) – required
- Text (58) – not required
- TransactTime (60) – required
Message description: A Start One Side Only Period Confirmation message is sent by the Euronext to confirm the reception of the Start One Side Only Period. This message is only available for Euronext markets.
The repeating group is not required in the message.
Definition: Refer to <msgdic> and add Start One Side Only Period Confirmation (MsgType = „U0505‟) message as described below:
How to customize a FIXML dictionary
In order to apply any customizations for standard FIXML Dictionary, it is necessary to do the following:
- Refer to fixml schema
- Apply changes
- Store changes to the file
Layers of FIXML schema:
| Layer | Description |
|---|---|
| fixml-datatypes-*-*.xsd | FIXML data types definition |
fixml-fields-base-*-*.xsd fixml-fields-impl-*-*.xsd | FIXML fields and enumerations definitions |
| Fixml-components-base-*-*.xsd | FIXML root elements and global component blocks definition |
| fixml-categoryName-*-*.xsd | FIXML messages and components for each message category in FIXML definition |
- *-* refers to FIX protocol version
- categoryName refers to FIXML category (per-trade; trade; order; etc) E.g. fixml-order-4-4.xsd refers to all messages for Single Order workflow in FIX 4.4 Call Action
For detailed information refer to:
- All standard FIXML schemas at: http://www.fixprotocol.org/specifications/
- FIXML Technical documentation: http://www.fixprotocol.org/specifications/TechDocFIXML
All examples below are provided based on FIX 4.4.
How to add a custom value to existing FIX tag
Example: Valid values for AllocRejCode (88) tag should be extended with custom value “14” (unknown clearing account).
Definition: Refer to fixml-fields-base-4-4.xsd and apply a custom value for AllocRejCode (88) in the following way (refer to bold dark blue):
How to change the ‘required’ attribute of a tag in the FIX message
Example: It is necessary to change the „required‟ attribute for the Password (554) tag in FIX message User Request (MsgType = „BE‟) from „not required‟ to „required‟
Definition: Refer to fixml-components-base-4-4.xsd and find User Request (MsgType = „BE‟) message definition. Find “Password” tag definition in message definition and change the attribute „use‟ (if not absent) to required as use = “required” (refer to marked bold dark blue).
How to change the ‘required’ attribute of a tag in component block
Example: It is necessary to change the „required‟ attribute for Commission (12) and Commission Type (13) tags in the Commission Data component block from „not required‟ to „required‟.
Definition: Refer to fixml-components-base-4-4.xsd section and find Commission Data component block definition. Refer to Commission (12) and Commission Type (13) tags definition and change attribute „use‟ (if not absent) to required as use = “required” (refer to marked bold dark blue).
How to change the ‘required’ attribute of a component block in the FIX message
Example: It is necessary to change the „required‟ attribute of the “Parties” component block in FIX message Settlement Instruction Request (MsgType = „AV‟) from „not required‟ to „required‟.
Definition: Refer to fixml-settlement-base-4-4.xsd and find Settlement Instruction Request (MsgType = „AV‟) message definition. Find “Parties” component block definition in message definition and change the „minOccurs‟ attribute to minOccurs="1" (refer to marked bold dark blue).
How to add a custom tag to the existing FIX message
Example 1: It is necessary to add custom tag PolicyCode (8060) as not required field in New Order Single (MsgType = „D‟) message. The tag has no predefined valid values; data type for values is String.
Definition:
1. Declare a custom FIX tag in the fields dictionary. Refer to fixml-fields-base-4-4.xsd section and define the following
2. Refer to fixml-order-base-4-4.xsd , find New Order Single (MsgType = „D‟) description and add PolicyCode (8060) as described below in bold dark blue:
Example 2: It is necessary to add a custom tag VTRejectReasonBid (8100) as a required field in Mass Quote Acknowledgement (MsgType = „b‟) message. The tag has the following predefined valid values:
- “0” – Exchange option
- “1” – Unknown or non-tradable contract
- “2” – Exchange closed
- “99” – Other
Definition:
1. Declare a custom FIX tag in the fields dictionary. Refer to fixml-fields-base-4-4.xsd section and define the following
2. Refer to fixml-fields-impl-4-4.xsd and declare:
3. Refer to fixml-quotation-base-4-4.xsd , find Mass Quote Acknowledgement (MsgType = „b‟) message description and add VTRejectReasonBid (8100) as described below in bold dark blue:
How to add a custom tag to the existing FIX component block
Example: It is necessary to add a custom tag ShareTier (8800) as not a required field in the „Commission‟ component block. The tag has the following predefined valid values: „A‟, „B‟, „C‟; data type for values is char.
Definition:
1. Declare a custom FIX tag in the fields dictionary. Refer to fixml-fields-base-4-4.xsd section and define the following
2. Refer to fixml-fields-impl-4-4.xsd and declare:
3. Refer to fixml-components-base-4-4.xsd, find „Commission‟ component block description and add ShareTier (8800) as described below in bold dark blue:
How to add custom repeating group to the existing FIX message
Example: It is necessary to add a custom repeating group in List Execute (MsgType = „L‟) message. The repeating group consists of the following fields:
- leading tag: NoTradingSessions (386)
- repeating group fields:
- start field: TradingSessionID (336)
- other fields: TradingSessionSubID (625)
The repeating group is not required in the message.
Definition:
1. Make sure that a repeating group is defined in the schema. „Trading Sessions‟ is a standard FIX repeating group which is defined in fixml-components-base-4-4.xsd as illustrated in the example below:
2. Refer to fixml-listorders-base-4-4.xsd, find List Execute (MsgType = „L‟) message description and add the repeating group as described below in bold dark blue:
The custom repeating group сan be added to the component block or into another repeating group in the same way.
How to add custom FIX message
Example: It is necessary to add a custom Start One Side Only Period Confirmation (MsgType = „U0505‟) message. The message consists of the following fields:
- ClOrdID (11) - required
- Side (54) – required
- Text (58) – not required
- TransactTime (60) – required
Message description: A Start One Side Only Period Confirmation message is sent by Euronext to confirm the reception of the Start One Side Only Period. This message is only available for Euronext markets.
The repeating group is not required in the message.
Definition:
1. Add a user-defined message to the list of FIXML categories. Refer to fixml-main-4-4.xsd and specify the following (marked bold dark blue):
2. Create the files:
a. fixml-userdefined-4-4.xsd
With the following content:
b. fixml-userdefined-impl-4-4.xsd
With the following content:
c. fixml-userdefined-base-4-4.xsd - in this file Start One Side Only Period Confirmation (MsgType = „U0505‟) message should be defined as given below:
