Trade model XML schema

This page documents the trademodels.xml file, which defines the state machines used to manage trading workflow in the Java Trading API, the C Trading API, and Caplin Trader’s Trading API.

XML schema

The XML schema document for the trademodels.xml file.

trademodel schema
trademodels.xsd
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="tradeModels">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="tradeModel" maxOccurs="unbounded" minOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="state" maxOccurs="unbounded" minOccurs="1">
                <xs:complexType mixed="true">
                  <xs:sequence>
                    <xs:element name="transition" maxOccurs="unbounded" minOccurs="0">
                      <xs:complexType mixed="true">
                        <xs:attribute type="xs:string" name="target" use="required"/>
                        <xs:attribute type="xs:string" name="trigger" use="required"/>
                        <xs:attribute type="xs:string" name="source" use="required"/>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                  <xs:attribute type="xs:string" name="name" use="required"/>
                  <xs:attribute type="xs:byte" name="timeout" use="optional"/>
                  <xs:attribute type="xs:string" name="timeoutState" use="optional"/>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
            <xs:attribute type="xs:string" name="name" use="required"/>
            <xs:attribute type="xs:string" name="initialState" use="required"/>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Elements and attributes

Elements and attributes in the trademodels.xml file.

<tradeModels>

The root element. Contains zero or more tradeModel elements.

<tradeModel>

A state model for a trade. Defines a set of states and transitions between states.

<tradeModel> attributes
Attribute Type Required Description

name

string

yes

The name of the trademodel. The name is used as an identifier and must be unique.

initialState

string

yes

A reference to the state element that defines the initial state of the tradeModel.

<state>

Describes a trading state.

<state> attributes
Attribute Type Required Description

name

string

yes

The name of the state. The name is used as an identifier and must be unique to the tradeModel.

timeout

byte

Reserved.

timeoutState

string

Reserved.

<transition>

Describes a transition from one trade model state to another. Defines the source and type of the triggering message, and the target state that the model transitions to.

<transition> attributes
Attribute Type Required Description

target

string

yes

The name of the state to transition to.

source

string

yes

The source of the message triggering the transition. Can be 'client' or 'server'.

trigger

string

yes

The type of message that triggers the transition (the value of the message’s MsgType field)

Example

The following example is an abridged version of the trademodels.xml file used by Caplin FX Suite applications and the FX Integration API.

Abridged trademodels.xml showing the ESP trade model
<?xml version="1.0" encoding="UTF-8" ?>
<tradeModels xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="trademodels.xsd">
  <tradeModel name="ESP" initialState="Initial">
    <state name="Initial" >
      <transition target="Submitted" trigger="Submit" source="client"/>
    </state>
    <state name="Submitted" timeout="10" timeoutState="Error">
      <transition target="Error" trigger="Error" source="server"/>
      <transition target="Queued" trigger="SubmitAck" source="server"/>
      <transition target="Rejected" trigger="Reject" source="server"/>
    </state>
    <state name="Error" />
    <state name="Queued" >
      <transition target="Error" trigger="Error" source="server"/>
      <transition target="PickedUp" trigger="PickUp" source="server"/>
      <transition target="Rejected" trigger="Reject" source="server"/>
      <transition target="ClientCloseSent" trigger="ClientClose" source="client"/>
    </state>
    <state name="PickedUp" >
      <transition target="Error" trigger="Error" source="server"/>
      <transition target="Queued" trigger="Hold" source="server"/>
      <transition target="TradeConfirmed" trigger="TradeConfirmation" source="server"/>
      <transition target="Rejected" trigger="Reject" source="server"/>
    </state>
    <state name="TradeConfirmed" />
    <state name="Rejected" />
    <state name="ClientCloseSent" >
      <transition target="ClientClosed" trigger="ClientCloseAck" source="server"/>
    </state>
    <state name="ClientClosed" />
  </tradeModel>
</tradeModels>

The state diagram below illustrates the workflow described in the XML above:

InitialSubmittedQueuedErrorRejectedClientCloseSentPickedUpTradeConfirmedClientClosedSubmitSubmitAckErrorRejectClientClosePickUpHoldErrorRejectTradeConfirmationErrorRejectClientCloseAckLegendTransitions initiated by the client are inyellow.Transitions initiated by the server are inblue.