# Trade model XML schema

This page documents the `trademodels.xml` file, which defines the state machines that manage trading workflow in the [Java Trading API](https://docs.caplin.com/developer/api/trading_java/latest/), the [C Trading API](https://docs.caplin.com/developer/api/trading_c/latest/), and Caplin Trader’s [Trading API](../../../caplin-trader/4/trading-api/index.md).

For example trade models, see the trade model XML files packaged with the example adapters in the [FX Integration API](../../../fx-integration-api/index.md) kit.

## XML schema

The XML schema document for the `trademodels.xml` file.

![Trade model schema](../../../images/trademodel_schema.svg)

**trademodels.xsd**

```xml
<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.

### &lt;tradeModels>

The root element. Contains zero or more `tradeModel` elements.

### &lt;tradeModel>

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

**&lt;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. |

### &lt;state>

Describes a trading state.

**&lt;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. |

### &lt;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.

**&lt;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](../../../fx-integration-api/index.md).

**Abridged trademodels.xml showing the ESP trade model**

```xml
<?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:

```plantuml
@startuml
[*] --> Initial<<Terminator>>
Initial -[#ECAF28]-> Submitted :  Submit
Submitted --> Queued : SubmitAck
Submitted --> Error : Error
Submitted --> Rejected : Reject

Queued -[#ECAF28]-> ClientCloseSent : ClientClose
Queued --> PickedUp : PickUp
Queued --> Error : Error
Queued --> Rejected : Reject

PickedUp --> Queued : Hold
PickedUp --> TradeConfirmed<<Terminator>> : TradeConfirmation
PickedUp --> Error : Error
PickedUp --> Rejected : Reject

ClientCloseSent --> ClientClosed<<Terminator>> : ClientCloseAck

TradeConfirmed --> [*]
ClientClosed --> [*]
Error<<Terminator>> --> [*]
Rejected<<Terminator>> --> [*]

legend left
**__Legend__**
Transitions initiated by the client are in <color:#ECAF28><b>yellow</b></color>.
Transitions initiated by the server are in <color:#003E67><b>blue</b></color>.
end legend

@enduml
```