Introduction

The goal of FinSpec is to define a standard, protocol-agnostic, digital specification to describe and document pre- and post-trade interfaces and workflows in financial services including (but not limited to) order entry, execution, market data, allocations and settlement.

Our hope is that the specification will allow both humans and computers to discover and understand the capabilities of an interface without needing to read through lengthy PDF documentation. As well as creating interactive API documentation, correctly formatted FinSpec documents can be used by developers to validate and mock APIs, acclerating development and reducing errors.

The current version of the FinSpec specification is 1.1: To read more about the schema definition: [Get Started].

The Schema comes with an open-source tool which allows you to instantly validate your files against the Schema before you deploy or share with counterparties. [Read More]

Revision History

Version Date Notes
[0.1] 2016-01-06 Initial release of FinSpec Specification.
[0.2] 2016-03-16 Datatypes related enhancements. Added conditions block to field.
[0.3] 2016-04-29 Add support for finite state machine workflow.
[1.0] 2017-02-28 Enhanced protocol metadata, informational messages and change history.
[1.1] 2017-03-10 Support for functional (context-specific) messages.

Roadmap

We continuously look into ways to improve our schema and make it as practical and useful for our community. Here are some future enhancements that we are currently working on:

If you have any ideas, comments on how to improve the schema further, please speak out! We rely on everyone’s input and contribution to make this project a success!

Support

You can leave all your comments and raise an issue directly on the GitHub page and we will get back to you promptly. Good enhancement ideas will be prioritised to be integrated in future releases. if there is any specific subject you want to discuss, you can also drop us a line at happytohelp@fixspec.com.

Schema Definition v1.1

Change log

Support for Functional (Context-Specific) Messages

One of the great challenges for developers reading financial services documentation is the lack of clarity around when certain message attributes or values are / are not permitted – how the context of a message adjusts it’s requirements. This problem is most accute with very overloaded messages such as algorithmic orders, but for the purpose of this introduction, we simply consider priced (Limit) vs unpriced (Market) orders in a FIX specification.

In FIX, the message to enter a new order is the NewOrderSingle. In “traditional” specifications, the NewOrderSingle message is presented once in all its glory, containing the superset of all possible fields and values. There are two that we will focus on here:

In most FIX specifications, you will see OrdType [40] marked as a mandatory field, and Price [44] marked as optional, as the single presentation must accomodate both the Market (where it should not be present at all), and Limit (where is it always required) cases. In other words the author is forced to compromise context-specific clarity in order to provide a single NewOrderSingle message description.

By allowing Functional Messages in the FinSpec schema, we are allowing authors to provide context-specific messages descriptions alongside the traditional superset view. Each Functional message is a complete description of a message within a specific context (removing all fields or values which are not relevant to that context, and adjusting descriptions or required status accordingly), along with an machine-readable context block codifying the context itself.

So for our example above, our FinSpec schema could feature the following:

  1. One “traditional” application message representing the superset position with:

    • OrdType[40] offering both 1 (Market) and 2 (Limit) as options.
    • Price [44] marked as optional
  2. A Market functional view with:

    • The set of permitted values for OrdType[40] reduced to only permit 1 (Market).
    • The Price[44] field removed completely.
  3. A Limit functional view with:

    • The set of permitted values for OrdType[40] reduced to only permit 2 (Limit).
    • The Price[44] field present and marked as always required.

This is - of course - a very simplistic case as a gentle introduction to this topic, but real-world algo specs contain a mass of such variances across various order strategies (captured as either large blocks or descriptive text or complex matricies). Since “traditional” specifications do not contain a digital representation of this context, the specifications must be read by a human with considerable skill and experience to understand, and carry a high risk of incorrect client coding.

Format

For example, if a field is said to have an array value, the JSON array representation will be used:

{
   "field" : [...]
}

The files describing the APIs in accordance with the FinSpec specification are represented as JSON objects and conform to the JSON standards.

All identifiers in the specification are case sensitive.

The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.

File Structure

The FinSpec representation of the API is made of a single file.

By convention, the API file has .json extension.

Vendor Extensions

While the FinSpec Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The extensions properties are always prefixed by "x-" and can have any valid JSON format value.

Field PatternTypeDescription
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object.

Objects

Root document

This is the root document object for the API specification.

Fixed Fields

Field Name Type Description
finspec string Required
Specifies the FinSpec Specification version being used. The value MUST be “1.0”.
info Info Required
Provides metadata about the specification. The metadata can be used by the clients if needed.
protocol Protocol Required
Metadata describing the protocol.
changes Changes Optional
A description of the changes made in this version of the API specification.
datatypes Datatype Required
A list of datatypes used in the API specification.
commonBlocks CommonBlocks Required (if supported by protocol)
A list of common blocks used by the messages in the API specification. e.g. Header, footer, etc.
messages Messages Required
A list of messages used in the API specification.
workflows Workflow Optional
A list of finite state machine style workflow (optional)

The Root object may contain vendor extensions.

Info

{
  "version": "11.5",
  "issueDate": "2015-08-26",
  "liveDate": "2015-08-26",
  "issuer": "FixSpec Ltd.",
  "title": "FixSpec Example FIX Specification",
  "logo": "https://fixspec.com/images/fixspec.jpg",
  "contacts": [
    {
    "name": "Customer Services",
    "phone": "+44 7908 860 436",
    "email": "happytohelp@fixspec.com",
    "url": "http://fixspec.com"
    }
  ]
}

The object provides metadata about the API specification.

Field Name Type Description
version string Required
A semantic version number of the API.
issuer string Required
The name of the API issuer.
issueDate string Required
The issue date of the API description expressed in YYYY-MM-DD format.
liveDate string Optional
The anticipated production-live date of the API description expressed in YYYY-MM-DD format.
title string Required
The title of the API service.
logo string Optional
A fully-qualified URL to a suitable logo image for the spec author.
contacts Contacts Optional
A List of contact details for the owners of the API.

The Info object may contain vendor extensions.

Contacts

[
    {
    "name": "Customer Services",
    "phone": "+44 7908 860 436",
    "email": "happytohelp@fixspec.com",
    "url": "http://fixspec.com"
    }
  ]

Contacts information for the specification.

Field Name Type Description
name string Required
The identifying name of the contact person/organization.
phone string See note below
The phone number (including international dialing code) for the contact.
url string See note below
The URL pointing to the contact information. MUST be in the format of a URL.
email string See note below
The email address of the contact person/organization. MUST be in the format of an email address.

NOTE: At least one of phone, url or email must be provided.

The Contact object may contain vendor extensions.

Protocol

{
  "protocol": {
    "name" : "FIX",
    "description": "FIX Protocol",
    "isFIX": true,
    "isOffsetBased": false,
    "isTagValue": true,
    "isBinary": false,
    "isObject": false,
    "charset": "UTF8",
    "hasHeader": true,
    "hasFooter": true
  }
}

The object provides metadata about the protocol.

Field Name Type Description
name string Required
The common name for the protocol.
description string Optional
An optional description of the protocol.
isFIX boolean See note below
Is this the FIX protocol? (Useful short-cut for one of the most popular protocols).
isOffsetBased boolean See note below
Is this a offset-based message such as ITCH?
isTagValue boolean See note below
Is the protocol tag-value based, such as FIX or SWIFT?
isObject boolean See note below
Does the specification describe the set of object attributes returned from an SDK?
isBinary boolean Optional (default to FALSE)
Indicates whether protocol is text or binary.
endianness string Required for binary protocols only
Default endianness of numerical types for binary/native APIs. Value MUST be from the list: "little" and "big".
charset string Optional
Legal character set used for string values e.g. ‘UTF8’, 'ISO 8859-1’, etc.
hasHeader boolean Optional
Do messages in this protocol always have a defined header block?
hasFooter boolean Optional
Do messages in this protocol always have a defined footer block?

NOTE: At least one of the following protocol attributes must be present: isFIX, isOffsetBased, isTagValue and isObject.

The Protocol object may contain vendor extensions.

Changes

{
  "changes": {
    "summary": "<p>These are my changes since the last known version</p>",
    "lastVersion": "11.2",
    "lastVersionDate": "2001-01-01",
    "history": [
      {
        "version": "11.1",
        "issueDate": "2016-10-08",
        "liveDate": "2016-10-08",
        "summary": "This is my summary of changes in the 11.1 version."
      }
    ]
  }
}

An optional block providing a description of changes in this, and prior, spec versions.

Field Name Type Description
summary string Required
A HTML or text description of the changes made.
lastVersion string Required
The version number of the immediately prior spec version (i.e. the starting spec to which changes have been applied).
lastVersionDate string Required
The date of the immediately prior spec version (i.e. the starting spec to which changes have been applied) in YYYY-MM-DD format.
history History Optional
A historical list of prior changes.

The Chnages object may contain vendor extensions.

History

{
  "version": "11.1",
  "issueDate": "2016-10-08",
  "liveDate": "2016-10-08",
  "summary": "This is my summary of changes in the 11.1 version."
}

An optional block providing a description of changes in this, and prior, spec versions.

Field Name Type Description
version string Required
The spec version number to which this history record relates.
issueDate string Required
The issue date of the spec to which this history record relates, in YYYY-MM-DD format.
liveDate string Optional
The live date of the spec version to which this history record relates, in YYYY-MM-DD format.
summary string Required
A HTML or text description of the changes applied in the indicated spec version.

The History object may contain vendor extensions.

Datatype

{
  "name": "Price",
  "baseType": "integer",
  "length": 8,
  "precision": 8,
  "description": "Eight byte integer field with eight implied decimal places."
}
{
  "name": "Qty",
  "baseType": "number",
  "description": "Float field capable of storing either a whole number (no decimal places) of 'shares' (securities denominated in whole units) or a decimal value containing decimal places for non-share quantity asset classes (securities denominated in fractional units)."
}
{
  "name": "MultipleStringValue",
  "baseType": "string",
  "description": "String field containing one or more space delimited multiple character values (e.g. |277=AV AN A| )."
}
{
  "name": "UInt32E",
  "baseType": "integer",
  "length": 4,
  "isUnsigned": true,
  "description": "Little-Endian encoded 32 bit unsigned integer."
}

Describes type of data stored in the field value of the API.

Field Name Type Description
name name Required
Name of the type. e.g. int, uint8e, Price, Boolean, etc.
baseType string Required
Specifies the base type of the value. Value MUST be fron the list: "char", "integer", "number", "string",
description string Required
HTML or text description of this type.
length integer Optional
Length of value for this type in number of bytes (binary) or characters (text).
precision integer Optional
Implied number of decimal places for floating numbers represented as integers.
isUnsigned boolean Optional
Whether numerical value is unsigned or not. Default: false
isBitField boolean Optional
Whether type represents a bit field. Default: false
pattern string Optional
Regular expression to describe the pattern of the value for this datatype.
padChar string Optional
Character used for padding.
padSide string Optional
Whether field value should be padded to left or right. Value MUST be from the list: "left" and "right".
examples Examples Optional
Array of examples to explain the datatype.

The Datatype object may contain vendor extensions.

CommonBlocks

{
  "header": {
      "name": "Standard FIX Header",
      "wireId": "header",
      "description": "The standard FIX message header",
      "fields": [...]
    },

  "footer": {
      "name": " Standard FIX Trailer",
      "wireId": "footer",
      "description": "The standard FIX message trailer",
      "fields": [...]
    }
}

A list of common blocks used in the messages in the API specification.

Field Name Type Description
header Message Required where expected by protocol
Common message header.
footer Message Required where expected by protocol
Common message footer.

The CommonBlock object may not contain vendor extensions.

Messages

{
  "info": [
    {
      "name": "Symbology",
      "description": "This is some text description of symbology demanded by the recipient."
    },
    {
      "name": "Market Phases",
      "description": "A HTML description of the trading phases of the venue"
    }
  ],
  "session": [
    {
      "name": "Logon",
      "wireId": "A",
      "description": "The Logon message authenticates a user establishing a connection to a remote system.",
      "fields": [...]
    },

    {
      "name": "Heartbeat",
      "wireId": "0",
      "description": "The Heartbeat monitors the status of the communication link and identifies when the last of a string of messages was not received.",
      "fields": [...]
    }
  ],
  "application": [
     {
        "name": "Order Single",
        "wireId": "D",
        "description": "The new order message type is used by institutions wishing to electronically submit orders.",
        "fields": [...]
      },
      {
        "name": "Order Cancel Request",
        "wireId": "F",
        "description": "...",
        "fields": [...]
      }
  ]
}

A list of all messages used in the API specification.

Field Name Type Description
info Message Optional
Series of free-text, descriptive sections which do not directly relate to messaging e.g. Symbology, Makret Phases etc.
session Message Optional
List of session level messages e.g. Logon, Heartbeat, etc.
application Message Required
List of application level messages e.g. New Order, Execution Report, etc.
functional MessageWithContext Optional
List of functional messages, which describe application messages within a given context.

The Messages object may contain vendor extensions.

Message

{
  "name": "NewOrderSingle",
  "wireId": "D",
  "direction": "in",
  "description": "...",
  "fields": [...]
}

A list of attributes collectively used to describe common block or the entire message in the specification.

Field Name Type Description
name string Required
Name of the message.
wireId string or integer Required (except info sections)
Wire identifier for the message (eg A for Logon in FIX).
description string Required
HMTL or plain text description of the purpose and use of the message.
direction string Optional
Indication of message flow. Value MUST be from the list: "in", "out", and "both". Default: both.
fields Field Required (except info sections)
List of fields available within a message.
examples Example Optional
List of message examples.

The Message object may contain vendor extensions.

MessageWithContext

{
  "name": "NewMarketOrder",
  "wireId": "D",
  "direction": "in",
  "description": "...",
  "context": {
    "expressionType": "groovy",
    "expression": "$40 == '1'",
    "description": "OrdType (40) equals 1 (Market)"
  },
  "fields": [...]
}

A description of a message within a defined context.

Field Name Type Description
name string Required
Name of the message.
wireId string or integer Required
Wire identifier for the message (eg A for Logon in FIX).
description string Required
HMTL or plain text description of the purpose and use of the message.
direction string Optional
Indication of message flow. Value MUST be from the list: "in", "out", and "both". Default: both.
context Context Required
Digital description of the intended message context.
fields Field Required
List of fields available within a message.
examples Example Optional
List of message examples.

The Message object may contain vendor extensions.

Context

{
  "expressionType": "groovy",
  "expression": "$40 == '1'",
  "description": "OrdType (40) equals 1 (Market)"
}

Used to provide a digital description of the context for a functional (context-specific) message.

Field Name Type Description
expressionType string Required
Type of grammar used in expression field. Value MUST be groovy or jsep. Default: groovy.
expression string Required
Expression. The message context is considered to be in effect if this expression evaluates to true.
description string Required
Human-readable description of the context.

The Context object may contain vendor extensions.

Field

{
  "position": 0,
  "name": "Header",
  "description": "Standard FIX header",
  "blockId": "header",
  "datatype": "block"
}
{
  "position": 45,
  "name": "ClearingAccount",
  "description": "Clearing Account Type",
  "datatype": "uInt8",
  "length": 1,
  "values": [
      {
          "enum": 1,
          "description": "Client"
      },
      {
          "enum": 3,
          "description": "House"
      }
  ]
}
{
  "position": 25,
  "alwaysRequired": false,
  "description": "Price per share",
  "wireId": "44",
  "datatype": "price"
}

Description of a specific field within a message.

Field Name Type Description
offset integer Required for offset-based protocols
Zero-based offset of the field within the message for binary APIs.
position integer Optional
Zero-based position of the field within the message for text/tag-value APIs. Where absent, ordering should be assumed from positioning within the JSON.
wireId string or integer Required for tag-value protocols
Wire identifier for the field (eg tag 35 in FIX). Either of wireId or blockId should be present.
blockId string Required to identify common header/footer only
Name of the block from the commonBlocks section. Either of wireId or blockId should be present.
description string Optional
Description of the purpose and use of the field.
name string Required
Name of the field.
datatype Datatype Required
Field datatype from the list of API datatypes.
minValue number Optional
Minimum permitted field value for numeric types. Default: zero.
maxValue number optional
Maximum permitted field value for numeric types. Default: unlimited
exclusiveMinValue boolean Optional
Whether 'minValue’ value is exclusive or not.
exclusiveMaxValue boolean optional
Whether 'maxValue’ value is exclusive or not.
minLength integer Optional
Minimum permitted length of value for string types.
maxLength integer Optional
Maximum permitted length of value for string types.
length integer Optional
Field value length in number of bytes (binary) or characters (text).
values Values Optional
List of possible values if the field is enumerated.
pattern string Optional
Regular expression to describe the pattern of the value for this field.
alwaysRequired boolean Optional
Boolean flag to indicate that this field is present in 100% of cases. Default for tag-value protocols: false
conditions Condition Optional
Field conditional requirements.
fields Field Optional
List of nested fields, indicating a repeating group under the current field.

The Field object may contain vendor extensions.

Values

{
  "wireValue": 1,
  "name": "Client" 
  "description": "This is a long description"
}

Description of an enumerated, valid value.

Field Name Type Description
wireValue string or number Required
Enumeration as it appears on the wire.
name string Required
Short, common name for this enumeration.
description string Optional
Longer description of enumerated value.
isDefault boolean Optional
Whether this value should be considered the default for the field if it is absent from the message.

The Values object may contain vendor extensions.

Condition

{
   "label": "PriceOnLimitOrder",
   "expressionType": "groovy",
   "expression": "($40 == 2)",
   "isReqd": true,
   "isAbsent": false
 }

In this example simple expression is used to define the conditions. This condition defines that if value of tag 40 is 2, given fields is required.

Field conditional requirements.

Field Name Type Description
label string Required
Name of the condition rule.
expressionType string Optional
Type of grammar used in expression field. Value MUST be "groovy" or "jsep". Default: groovy.
expression string Required
Condition expression. This block will only take effect if this expression evaluates to true.
isReqd boolean Required
Field is mandatory in such condition.
isAbsent boolean Required
Field should not be present in such condition.
values Values OptionalList of (restricted) set of valid values if the expression evaluates to true.

The Condition object may contain vendor extensions.

Condition Expression Grammar

Field 40 must equal a value of 2
($40 == 2)
Field 40 may equal 3 or 4
($40 == 3)  || ($40 == 4)
Field 40 must have a value of 2, and field 44 must be greater than zero
($40 == 2) && ($44 > 0)
Field 44 must be present
$44
Field 44 must NOT be present
!$44
($2_OrderQty > 100)

In simple terms, it’s a conditional expression used in if statements which evaluates to true or false.

For tag values based APIs, value of the tag is expressed as: $<wireId> e.g. $40

For others e.g. native APIs, value of field is expressed as: $<position>_<name> e.g. $2_Price

Tokens that can be used in condition expression are:

  1. Comparison operators e.g. ==, >, etc.

  2. Logical operators e.g. &&, ||, etc.

  3. Brackets

  4. Use of ! to indicate 'not’

  5. In the case of Groovy, the comparison operator of ==~ may be used to indicate a regular expression.

Example

{
  "example": "8=FIX.4.2|9=69|5=A|34=12|49=SENDER|52=20140228-05:42:38.026|56=TARGET|98=0|108=120|10=238|",
  "description": "Market order example"
}

An example of the specified message. While we encourage placing the message example in the example attribute itself, this is optional should it be too restrictive for the use case. In such cases, the example should be placed in the description instead. TIP: Use the HTML tag <code> to format messages nicely.

Field Name Type Description
example string Optional
Actual example.
description string Required
Description (or purpose) of the example.

The Example object may contain vendor extensions.

Workflows

The workflows section is an array of workflow objects defined as follow:

Field Name Type Description
name string Required
Name of the workflow.
description string Required
Description of the specific workflow being modeled
includeMessages Array Required
List of messages (wireId) included in the workflow
states Array Required
list of possible individual states the object (e.g. Orders, Quote) can take in the workflow
transitions Array Required
Description of transitions (including triggering event - FIX msg - and resulting state)

The Workflow object may not contain vendor extensions.

IncludeMessage

{
      "messageType": ["D","F","G","8"],
      "linkedBy": ["$11", "$41", "$37"]
}

The array consists of IncludeMessage objects defined by the following fields:

Field Name Type Description
messageType array Required
Comma-separated wireID corresponding to messages involved in this workflow.
linkedBy array Optional
Field (wireID) that link all those messages together.

The IncludeMessage object may not contain vendor extensions.

State

{
    "ref": "Order.Acknowledged",
    "name": "Acknowledged",
    "isInitial": true,
    "description": "Unacknowledged, new order sent to target recipient"
}

The 'states’ array is a list of state objects which are defined by the fields below:

Field Name Type Description
ref string Required
Reference of the object state. It needs to be unique and will be used in the start and end fields
name string Required
Name given to this specific state
isInitial boolean Required
Is this an initial state? can not transition from any other state.
isFinal boolean Required
Is this a final state? Can not transition to any further state.
description string Description of this specific state

NOTE: Within an array of States, it is expected that exactly one state is marked as isInitial, and a second state is marked as isFinal.

The State object may not contain vendor extensions.

Transition

{
    "description": "Cancellation of an open order",
    "start": ["Order.Acknowledged","Order.PartiallyFilled"],
    "triggerBy" : {
        "messageWireId": "F"
    },
    "responses": [
        {
            "messageWireId": "9",
            "where": {
                "expressionType": "groovy",
                "expression": "($150 == 4)&($39 == 0)"
              },
            "end": "Order.Acknowledged",
            "isSuccess": false
        },
        {
            "messageWireId": "9",
            "where": {
                "expressionType": "groovy",
                "expression": "($150 == 4)&($39 == 1)"
              },
            "end": "Order.PartiallyFilled",
            "isSuccess": false
        },
        {
            "messageWireId": "8",
            "where": {
                "expressionType": "groovy",
                "expression": "($150 == 4)&($39 == 4)"
              },
            "end": "Order.Closed",
            "isSuccess": true
        }
    ]
}

The 'transitions’ array is composed of 'transition’ objects which are defined by the fields below:

Field Name Type Description
description string Required
Description of this transition
transitionStartstart Array Required
List of states the transition can iniate from.
triggerBytriggerBy TriggerBy OptionalSolicited message (Action) required to trigger the transition.
responses Array Required
List of possible responses: messages with field conditions.

The Transition object may not contain vendor extensions.

TriggerBy

Field Name Type Description
messageWireId string Required
WireID of the message that trigger this transition.

The TriggerBy object may not contain vendor extensions.

Response

Field Name Type Description
messageWireId string Required
WireID of the response message
where Where Required
Specific field condition in the message, expressed as a groovy expression.
end string Required
Resulting state at the end of the transition
isSuccess boolean Required
Did the transition successfully complete?

The Response object may not contain vendor extensions.

Where

Field Name Type Description
expressionType string Required
Type of grammar used in expression field. Value MUST be "jsep" or "groovy".
expression string Required
Condition expression.

The Where object may not contain vendor extensions.

Schema Definition v1.0

Change log

Enhanced Protocol Metadata

From the start, the FinSpec schema has been designed to handle any protocol - from tag/value protocols such as FIX or SWIFT, to offset-based protocols such as ITCH, and even support the description of objects returned from an SDK.

In prior versions of the schema, however, simply restricted protocol metadata to a simple label, and a binary boolean indicator. Version 1.0 adds a protocol object, allowing an extended metadata to be presented.

Support for Issuer Logos

The info object now supports an optional URL pointing to a logo for the issuer.

Change History

Understanding what has changed between two spec versions is very important for users. Of course this could be technically achieved by simply diff'ing the FinSpec JSON files, but it is also helpful to capture a text description of changes as typically presented in change history logs of specifications. A new changes object has been introduced to support this requirement.

Informational (non-Field) Messages

Version 1.0 adds a new information message type, that may be used to capture informational detail as simply free-text or HTML. Examples of informational sections may include detail around symbology or trading hours / phases.

Groovy Support For Field Conditions

Prior to version 1.0, the expression language used for describing field relationships in the condition object was Javascript Expressions (jsep). Version 1.0 extends and defaults this to groovy scripts.

Enumerated Wire Values

In version 0.3, enumerated values within a field were described by two values only - enum and description. In version 1.0, enum has been replaced by wireValue to more correctly capture it’s intended purpose as the representation on the wire, and a new (optional) name attribute is added to allow a short enumerated label to be added.

Examples

We have provided some simple examples on Github to illustrate how FinSpec JSON files should be constructed.

Both a FIX and ITCH example are provided, including (non-exhaustive) workflow structures to model the life of a FIX order, and some administratvie market data messages.

Format

For example, if a field is said to have an array value, the JSON array representation will be used:

{
   "field" : [...]
}

The files describing the APIs in accordance with the FinSpec specification are represented as JSON objects and conform to the JSON standards.

All identifiers in the specification are case sensitive.

The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.

File Structure

The FinSpec representation of the API is made of a single file.

By convention, the API file has .json extension.

Vendor Extensions

While the FinSpec Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The extensions properties are always prefixed by "x-" and can have any valid JSON format value.

Field PatternTypeDescription
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object.

Objects

Root document

This is the root document object for the API specification.

Fixed Fields

Field Name Type Description
finspec string Required
Specifies the FinSpec Specification version being used. The value MUST be “1.0”.
info Info Required
Provides metadata about the specification. The metadata can be used by the clients if needed.
protocol Protocol Required
Metadata describing the protocol.
changes Changes Optional
A description of the changes made in this version of the API specification.
datatypes Datatype Required
A list of datatypes used in the API specification.
commonBlocks CommonBlocks Required (if supported by protocol)
A list of common blocks used by the messages in the API specification. e.g. Header, footer, etc.
messages Messages Required
A list of messages used in the API specification.
workflows Workflow Optional
A list of finite state machine style workflow (optional)

The Root object may contain vendor extensions.

Info

{
  "version": "11.5",
  "issueDate": "2015-08-26",
  "liveDate": "2015-08-26",
  "issuer": "FixSpec Ltd.",
  "title": "FixSpec Example FIX Specification",
  "logo": "https://fixspec.com/images/fixspec.jpg",
  "contacts": [
    {
    "name": "Customer Services",
    "phone": "+44 7908 860 436",
    "email": "happytohelp@fixspec.com",
    "url": "http://fixspec.com"
    }
  ]
}

The object provides metadata about the API specification.

Field Name Type Description
version string Required
A semantic version number of the API.
issuer string Required
The name of the API issuer.
issueDate string Required
The issue date of the API description expressed in YYYY-MM-DD format.
liveDate string Optional
The anticipated production-live date of the API description expressed in YYYY-MM-DD format.
title string Required
The title of the API service.
logo string Optional
A fully-qualified URL to a suitable logo image for the spec author.
contacts Contacts Optional
A List of contact details for the owners of the API.

The Info object may contain vendor extensions.

Contacts

[
    {
    "name": "Customer Services",
    "phone": "+44 7908 860 436",
    "email": "happytohelp@fixspec.com",
    "url": "http://fixspec.com"
    }
  ]

Contacts information for the specification.

Field Name Type Description
name string Required
The identifying name of the contact person/organization.
phone string See note below
The phone number (including international dialing code) for the contact.
url string See note below
The URL pointing to the contact information. MUST be in the format of a URL.
email string See note below
The email address of the contact person/organization. MUST be in the format of an email address.

NOTE: At least one of phone, url or email must be provided.

The Contact object may contain vendor extensions.

Protocol

{
  "protocol": {
    "name" : "FIX",
    "description": "FIX Protocol",
    "isFIX": true,
    "isOffsetBased": false,
    "isTagValue": true,
    "isBinary": false,
    "isObject": false,
    "charset": "UTF8",
    "hasHeader": true,
    "hasFooter": true
  }
}

The object provides metadata about the protocol.

Field Name Type Description
name string Required
The common name for the protocol.
description string Optional
An optional description of the protocol.
isFIX boolean See note below
Is this the FIX protocol? (Useful short-cut for one of the most popular protocols).
isOffsetBased boolean See note below
Is this a offset-based message such as ITCH?
isTagValue boolean See note below
Is the protocol tag-value based, such as FIX or SWIFT?
isObject boolean See note below
Does the specification describe the set of object attributes returned from an SDK?
isBinary boolean Optional (default to FALSE)
Indicates whether protocol is text or binary.
endianness string Required for binary protocols only
Default endianness of numerical types for binary/native APIs. Value MUST be from the list: "little" and "big".
charset string Optional
Legal character set used for string values e.g. ‘UTF8’, 'ISO 8859-1’, etc.
hasHeader boolean Optional
Do messages in this protocol always have a defined header block?
hasFooter boolean Optional
Do messages in this protocol always have a defined footer block?

NOTE: At least one of the following protocol attributes must be present: isFIX, isOffsetBased, isTagValue and isObject.

The Protocol object may contain vendor extensions.

Changes

{
  "changes": {
    "summary": "<p>These are my changes since the last known version</p>",
    "lastVersion": "11.2",
    "lastVersionDate": "2001-01-01",
    "history": [
      {
        "version": "11.1",
        "issueDate": "2016-10-08",
        "liveDate": "2016-10-08",
        "summary": "This is my summary of changes in the 11.1 version."
      }
    ]
  }
}

An optional block providing a description of changes in this, and prior, spec versions.

Field Name Type Description
summary string Required
A HTML or text description of the changes made.
lastVersion string Required
The version number of the immediately prior spec version (i.e. the starting spec to which changes have been applied).
lastVersionDate string Required
The date of the immediately prior spec version (i.e. the starting spec to which changes have been applied) in YYYY-MM-DD format.
history History Optional
A historical list of prior changes.

The Chnages object may contain vendor extensions.

History

{
  "version": "11.1",
  "issueDate": "2016-10-08",
  "liveDate": "2016-10-08",
  "summary": "This is my summary of changes in the 11.1 version."
}

An optional block providing a description of changes in this, and prior, spec versions.

Field Name Type Description
version string Required
The spec version number to which this history record relates.
issueDate string Required
The issue date of the spec to which this history record relates, in YYYY-MM-DD format.
liveDate string Optional
The live date of the spec version to which this history record relates, in YYYY-MM-DD format.
summary string Required
A HTML or text description of the changes applied in the indicated spec version.

The History object may contain vendor extensions.

Datatype

{
  "name": "Price",
  "baseType": "integer",
  "length": 8,
  "precision": 8,
  "description": "Eight byte integer field with eight implied decimal places."
}
{
  "name": "Qty",
  "baseType": "number",
  "description": "Float field capable of storing either a whole number (no decimal places) of 'shares' (securities denominated in whole units) or a decimal value containing decimal places for non-share quantity asset classes (securities denominated in fractional units)."
}
{
  "name": "MultipleStringValue",
  "baseType": "string",
  "description": "String field containing one or more space delimited multiple character values (e.g. |277=AV AN A| )."
}
{
  "name": "UInt32E",
  "baseType": "integer",
  "length": 4,
  "isUnsigned": true,
  "description": "Little-Endian encoded 32 bit unsigned integer."
}

Describes type of data stored in the field value of the API.

Field Name Type Description
name name Required
Name of the type. e.g. int, uint8e, Price, Boolean, etc.
baseType string Required
Specifies the base type of the value. Value MUST be fron the list: "char", "integer", "number", "string",
description string Required
HTML or text description of this type.
length integer Optional
Length of value for this type in number of bytes (binary) or characters (text).
precision integer Optional
Implied number of decimal places for floating numbers represented as integers.
isUnsigned boolean Optional
Whether numerical value is unsigned or not. Default: false
isBitField boolean Optional
Whether type represents a bit field. Default: false
pattern string Optional
Regular expression to describe the pattern of the value for this datatype.
padChar string Optional
Character used for padding.
padSide string Optional
Whether field value should be padded to left or right. Value MUST be from the list: "left" and "right".
examples Examples Optional
Array of examples to explain the datatype.

The Datatype object may contain vendor extensions.

CommonBlocks

{
  "header": {
      "name": "Standard FIX Header",
      "wireId": "header",
      "description": "The standard FIX message header",
      "fields": [...]
    },

  "footer": {
      "name": " Standard FIX Trailer",
      "wireId": "footer",
      "description": "The standard FIX message trailer",
      "fields": [...]
    }
}

A list of common blocks used in the messages in the API specification.

Field Name Type Description
header Message Required where expected by protocol
Common message header.
footer Message Required where expected by protocol
Common message footer.

The CommonBlock object may not contain vendor extensions.

Messages

{
  "info": [
    {
      "name": "Symbology",
      "description": "This is some text description of symbology demanded by the recipient."
    },
    {
      "name": "Market Phases",
      "description": "A HTML description of the trading phases of the venue"
    }
  ],
  "session": [
    {
      "name": "Logon",
      "wireId": "A",
      "description": "The Logon message authenticates a user establishing a connection to a remote system.",
      "fields": [...]
    },

    {
      "name": "Heartbeat",
      "wireId": "0",
      "description": "The Heartbeat monitors the status of the communication link and identifies when the last of a string of messages was not received.",
      "fields": [...]
    }
  ],
  "application": [
     {
        "name": "Order Single",
        "wireId": "D",
        "description": "The new order message type is used by institutions wishing to electronically submit orders.",
        "fields": [...]
      },
      {
        "name": "Order Cancel Request",
        "wireId": "F",
        "description": "...",
        "fields": [...]
      }
  ]
}

A list of all messages used in the API specification.

Field Name Type Description
info Message Optional
Series of free-text, descriptive sections which do not directly relate to messaging e.g. Symbology, Makret Phases etc.
session Message Optional
List of session level messages e.g. Logon, Heartbeat, etc.
application Message Required
List of application level messages e.g. New Order, Execution Report, etc.

The Messages object may contain vendor extensions.

Message

{
  "name": "NewOrderSingle",
  "wireId": "D",
  "direction": "in",
  "description": "...",
  "fields": [...]
}

A list of attributes collectively used to describe common block or the entire message in the specification.

Field Name Type Description
name string Required
Name of the message.
wireId string or integer Required (except info sections)
Wire identifier for the message (eg A for Logon in FIX).
description string Required
HMTL or plain text description of the purpose and use of the message.
direction string Optional
Indication of message flow. Value MUST be from the list: "in", "out", and "both". Default: both.
fields Field Required (except info sections)
List of fields available within a message.
examples Example Optional
List of message examples.

The Message object may contain vendor extensions.

Field

{
  "position": 0,
  "name": "Header",
  "description": "Standard FIX header",
  "blockId": "header",
  "datatype": "block"
}
{
  "position": 45,
  "name": "ClearingAccount",
  "description": "Clearing Account Type",
  "datatype": "uInt8",
  "length": 1,
  "values": [
      {
          "enum": 1,
          "description": "Client"
      },
      {
          "enum": 3,
          "description": "House"
      }
  ]
}
{
  "position": 25,
  "alwaysRequired": false,
  "description": "Price per share",
  "wireId": "44",
  "datatype": "price"
}

Description of a specific field within a message.

Field Name Type Description
offset integer Required for offset-based protocols
Zero-based offset of the field within the message for binary APIs.
position integer Optional
Zero-based position of the field within the message for text/tag-value APIs. Where absent, ordering should be assumed from positioning within the JSON.
wireId string or integer Required for tag-value protocols
Wire identifier for the field (eg tag 35 in FIX). Either of wireId or blockId should be present.
blockId string Required to identify common header/footer only
Name of the block from the commonBlocks section. Either of wireId or blockId should be present.
description string Optional
Description of the purpose and use of the field.
name string Required
Name of the field.
datatype Datatype Required
Field datatype from the list of API datatypes.
minValue number Optional
Minimum permitted field value for numeric types. Default: zero.
maxValue number optional
Maximum permitted field value for numeric types. Default: unlimited
exclusiveMinValue boolean Optional
Whether 'minValue’ value is exclusive or not.
exclusiveMaxValue boolean optional
Whether 'maxValue’ value is exclusive or not.
minLength integer Optional
Minimum permitted length of value for string types.
maxLength integer Optional
Maximum permitted length of value for string types.
length integer Optional
Field value length in number of bytes (binary) or characters (text).
values Values Optional
List of possible values if the field is enumerated.
pattern string Optional
Regular expression to describe the pattern of the value for this field.
alwaysRequired boolean Optional
Boolean flag to indicate that this field is present in 100% of cases. Default for tag-value protocols: false
conditions Condition Optional
Field conditional requirements.
fields Field Optional
List of nested fields, indicating a repeating group under the current field.

The Field object may contain vendor extensions.

Values

{
  "wireValue": 1,
  "name": "Client" 
  "description": "This is a long description"
}

Description of an enumerated, valid value.

Field Name Type Description
wireValue string or number Required
Enumeration as it appears on the wire.
name string Required
Short, common name for this enumeration.
description string Optional
Longer description of enumerated value.
isDefault boolean Optional
Whether this value should be considered the default for the field if it is absent from the message.

The Values object may contain vendor extensions.

Condition

{
   "label": "PriceOnLimitOrder",
   "expressionType": "groovy",
   "expression": "($40 == 2)",
   "isReqd": true,
   "isAbsent": false
 }

In this example simple expression is used to define the conditions. This condition defines that if value of tag 40 is 2, given fields is required.

Field conditional requirements.

Field Name Type Description
label string Required
Name of the condition rule.
expressionType string Optional
Type of grammar used in expression field. Value MUST be "groovy" or "jsep". Default: groovy.
expression string Required
Condition expression. This block will only take effect if this expression evaluates to true.
isReqd boolean Required
Field is mandatory in such condition.
isAbsent boolean Required
Field should not be present in such condition.
values Values OptionalList of (restricted) set of valid values if the expression evaluates to true.

The Condition object may contain vendor extensions.

Condition Expression Grammar

($40 == 2)
($40 == 3)  || ($40 == 4)
($40 == 2) && ($44 > 0)
($2_OrderQty > 100)

In simple terms, it’s a conditional expression used in if statements which evaluates to true or false.

For tag values based APIs, value of the tag is expressed as: $<wireId> e.g. $40

For others e.g. native APIs, value of field is expressed as: $<position>_<name> e.g. $2_Price

Tokens that can be used in condition expression are:

  1. Comparison operators e.g. ==, >, etc.

  2. Logical operators e.g. &&, ||, etc.

  3. Brackets

Example

{
  "example": "8=FIX.4.2|9=69|5=A|34=12|49=SENDER|52=20140228-05:42:38.026|56=TARGET|98=0|108=120|10=238|",
  "description": "Market order example"
}

An example of the specified message. While we encourage placing the message example in the example attribute itself, this is optional should it be too restrictive for the use case. In such cases, the example should be placed in the description instead. TIP: Use the HTML tag <code> to format messages nicely.

Field Name Type Description
example string Optional
Actual example.
description string Required
Description (or purpose) of the example.

The Example object may contain vendor extensions.

Workflows

The workflows section is an array of workflow objects defined as follow:

Field Name Type Description
name string Required
Name of the workflow.
description string Required
Description of the specific workflow being modeled
includeMessages Array Required
List of messages (wireId) included in the workflow
states Array Required
list of possible individual states the object (e.g. Orders, Quote) can take in the workflow
transitions Array Required
Description of transitions (including triggering event - FIX msg - and resulting state)

The Workflow object may not contain vendor extensions.

IncludeMessage

{
      "messageType": ["D","F","G","8"],
      "linkedBy": ["$11", "$41", "$37"]
}

The array consists of IncludeMessage objects defined by the following fields:

Field Name Type Description
messageType array Required
Comma-separated wireID corresponding to messages involved in this workflow.
linkedBy array Optional
Field (wireID) that link all those messages together.

The IncludeMessage object may not contain vendor extensions.

State

{
    "ref": "Order.Acknowledged",
    "name": "Acknowledged",
    "isInitial": true,
    "description": "Unacknowledged, new order sent to target recipient"
}

The 'states’ array is a list of state objects which are defined by the fields below:

Field Name Type Description
ref string Required
Reference of the object state. It needs to be unique and will be used in the start and end fields
name string Required
Name given to this specific state
isInitial boolean Required
Is this an initial state? can not transition from any other state.
isFinal boolean Required
Is this a final state? Can not transition to any further state.
description string Description of this specific state

NOTE: Within an array of States, it is expected that exactly one state is marked as isInitial, and a second state is marked as isFinal.

The State object may not contain vendor extensions.

Transition

{
    "description": "Cancellation of an open order",
    "start": ["Order.Acknowledged","Order.PartiallyFilled"],
    "triggerBy" : {
        "messageWireId": "F"
    },
    "responses": [
        {
            "messageWireId": "9",
            "where": {
                "expressionType": "groovy",
                "expression": "($150 == 4)&($39 == 0)"
              },
            "end": "Order.Acknowledged",
            "isSuccess": false
        },
        {
            "messageWireId": "9",
            "where": {
                "expressionType": "groovy",
                "expression": "($150 == 4)&($39 == 1)"
              },
            "end": "Order.PartiallyFilled",
            "isSuccess": false
        },
        {
            "messageWireId": "8",
            "where": {
                "expressionType": "groovy",
                "expression": "($150 == 4)&($39 == 4)"
              },
            "end": "Order.Closed",
            "isSuccess": true
        }
    ]
}

The 'transitions’ array is composed of 'transition’ objects which are defined by the fields below:

Field Name Type Description
description string Required
Description of this transition
transitionStartstart Array Required
List of states the transition can iniate from.
triggerBytriggerBy TriggerBy OptionalSolicited message (Action) required to trigger the transition.
responses Array Required
List of possible responses: messages with field conditions.

The Transition object may not contain vendor extensions.

TriggerBy

Field Name Type Description
messageWireId string Required
WireID of the message that trigger this transition.

The TriggerBy object may not contain vendor extensions.

Response

Field Name Type Description
messageWireId string Required
WireID of the response message
where Where Required
Specific field condition in the message, expressed as a groovy expression.
end string Required
Resulting state at the end of the transition
isSuccess boolean Required
Did the transition successfully complete?

The Response object may not contain vendor extensions.

Where

Field Name Type Description
expressionType string Required
Type of grammar used in expression field. Value MUST be "jsep" or "groovy".
expression string Required
Condition expression.

The Where object may not contain vendor extensions.

Schema Definition v0.3

Change log

Support for finite state machine workflows

With version 0.3 we introduce support for workflows, and more precisely: finite state machine (FSM) workflow. The schema allows to define states, transitions, and actions and map them together. FSM workflows are relatively more technical than traditional sequential workflows, but their main advantage is to allow for full representation of a life of an object (Order, Quotes, etc…)

This version comes with a simple nonexhaustive example which illustrates how to use the workflow structure to model the life of an order. Below is the diagram representation of this model:

alt tag

Format

For example, if a field is said to have an array value, the JSON array representation will be used:

{
   "field" : [...]
}

The files describing the APIs in accordance with the FinSpec specification are represented as JSON objects and conform to the JSON standards.

All identifiers in the specification are case sensitive.

The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.

File Structure

The FinSpec representation of the API is made of a single file.

By convention, the API file has .json extension.

Vendor Extensions

While the FinSpec Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The extensions properties are always prefixed by "x-" and can have any valid JSON format value.

Objects

Root document

This is the root document object for the API specification.

Fixed Fields

Field Name Type Description
finspec string Required. Specifies the FinSpec Specification version being used. The value MUST be “0.3”.
info Info Object Required. Provides metadata about the specification. The metadata can be used by the clients if needed.
protocol string Required. Underlying protocol used by the specification. e.g. fix, itch, proprietary, etc.
protocolVersion string Version of the underlying protocol used by the API specification if applicable. e.g. 4.2 for FIX protocol.
isBinary boolean Required. Indicates whether protocol is text or binary.
charset string Legal character set used for string values e.g. ‘UTF8’, 'ISO 8859-1’, etc.
endianness string Default endianness of numerical types for binary/native APIs. alue MUST be from the list: "little" and "big".
datatypes [Datatype Object] Required. A list of datatypes used in the API specification.
commonBlocks CommonBlocks Object A list of common blocks used by the messages in the API specification. e.g. Header, footer, etc.
messages Messages Object A list of messages used in the API specification.
workflows Workflow Array A list of finite state machine style workflow (optional)

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Info

{
  "version": "11.5",
  "issueDate": "2015-08-26",
  "liveDate": "2015-08-26",
  "issuer": "FixSpec Ltd.",
  "title": "FixSpec Example FIX Specification",
  "contacts": [
    {
    "name": "Customer Services",
    "phone": "+44 7908 860 436",
    "email": "happytohelp@fixspec.com",
    "url": "http://fixspec.com"
    }
  ]
}

The object provides metadata about the API specification.

Field Name Type Description
version string Required. A semantic version number of the API.
issuer string The name of the API issuer.
issueDate string Required. The issue date of the API description expressed in YYYY-MM-DD format.
liveDate string The anticipated production-live date of the API description expressed in YYYY-MM-DD format.
title string Required. A unique and precise title of the API service.
contacts Contacts Object A List of contact details for the owners of the API.

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Contacts

[
    {
    "name": "Customer Services",
    "phone": "+44 7908 860 436",
    "email": "happytohelp@fixspec.com",
    "url": "http://fixspec.com"
    }
  ]

Contacts information for the specification.

Field Name Type Description
name string The identifying name of the contact person/organization.
phone string The phone number (including international dialing code) for the contact.
url string The URL pointing to the contact information. MUST be in the format of a URL.
email string The email address of the contact person/organization. MUST be in the format of an email address.

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Datatype

{
  "name": "Price",
  "baseType": "integer",
  "length": 8,
  "precision": 8,
  "description": "Eight byte integer field with eight implied decimal places."
}
{
  "name": "Qty",
  "baseType": "number",
  "description": "Float field capable of storing either a whole number (no decimal places) of 'shares' (securities denominated in whole units) or a decimal value containing decimal places for non-share quantity asset classes (securities denominated in fractional units)."
}
{
  "name": "MultipleStringValue",
  "baseType": "string",
  "description": "String field containing one or more space delimited multiple character values (e.g. |277=AV AN A| )."
}
{
  "name": "UInt32E",
  "baseType": "integer",
  "length": 4,
  "isUnsigned": true,
  "description": "Little-Endian encoded 32 bit unsigned integer."
}

Describes type of data stored in the field value of the API.

Field Name Type Description
name name Required. Name of the type. e.g. int, uint8e, Price, Boolean, etc.
baseType string Required. Specifies the base type of the value. Value MUST be fron the list: "char", "integer", "number", "string",
length integer Length of value for this type in number of bytes.
precision integer Precision for floating point type value.
isUnsigned boolean Whether numerical value is unsigned or not. Default: false
isBitField boolean Whether type represents a bit field. Default: false
pattern string Regular expression to describe the pattern of the value for this datatype.
padChar string Character used for padding.
padSide string Whether field value should be padded to left or right. Value MUST be from the list: "left" and "right".
description string Required. Description/remark for this type.

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

CommonBlocks

{
  "header": {
      "name": "Standard FIX Header",
      "wireId": "header",
      "description": "The standard FIX message header",
      "fields": [...]
    },

  "footer": {
      "name": " Standard FIX Trailer",
      "wireId": "footer",
      "description": "The standard FIX message trailer",
      "fields": [...]
    }
}

A list of common blocks used in the messages in the API specification.

Field Name Type Description
header Message Object Common message header.
footer Message Object Common message footer.

Messages

{
  "session": [
    {
      "name": "Logon",
      "wireId": "A",
      "description": "The Logon message authenticates a user establishing a connection to a remote system.",
      "fields": [...]
    },

    {
      "name": "Heartbeat",
      "wireId": "0",
      "description": "The Heartbeat monitors the status of the communication link and identifies when the last of a string of messages was not received.",
      "fields": [...]
    }
  ],
  "application": [
     {
        "name": "Order Single",
        "wireId": "D",
        "description": "The new order message type is used by institutions wishing to electronically submit orders.",
        "fields": [...]
      },
      {
        "name": "Order Cancel Request",
        "wireId": "F",
        "description": "...",
        "fields": [...]
      }
  ]
}

A list of all messages used in the API specification.

Field Name Type Description
session [Message Object] List of session level messages e.g. Logon, Heartbeat, etc.
application [Message Object] List of application level messages e.g. New Order, Execution Report, etc.

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Message

{
  "name": "NewOrderSingle",
  "wireId": "D",
  "direction": "in",
  "description": "...",
  "fields": [...]
}

A list of fields collectively used to describe common block or the entire message in the specification.

Field Name Type Description
name string Required. Name of the message.
wireId string or integer Required. Wire identifier for the message (eg A for Logon in FIX).
description string Required. Description of the purpose and use of the message.
direction string Required. Indication of message flow. Value MUST be from the list: "in", "out", and "both".
fields [Field Object] Required. List of fields available within a message.
examples [Example Object] List of message examples.

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Field

{
  "position": 0,
  "name": "Header",
  "description": "Standard FIX header",
  "blockId": "header",
  "datatype": "block"
}
{
  "position": 45,
  "name": "ClearingAccount",
  "description": "Clearing Account Type",
  "datatype": "uInt8",
  "length": 1,
  "values": [
      {
          "enum": 1,
          "description": "Client"
      },
      {
          "enum": 3,
          "description": "House"
      }
  ]
}
{
  "position": 25,
  "alwaysRequired": false,
  "description": "Price per share",
  "wireId": "44",
  "datatype": "price"
}

Description of a specific field within a message.

Field Name Type Description
offset integer Zero-based offset of the field within the message for binary APIs.
position integer Zero-based position of the field within the message for text/tag-value APIs.
wireId string or integer Wire identifier for the field (eg tag 35 in FIX). Either of wireId or blockId should be present.
blockId string Name of the block from the commonBlocks section. Either of wireId or blockId should be present.
description string Description of the purpose and use of the field.
name string Required. Name of the field.
datatype [Datatype Object] Required. Field datatype from the list of API datatypes.
minValue number Minimum permitted field value for numeric types.
maxValue number Maximum permitted field value for numeric types.
exclusiveMinValue boolean Whether 'minValue’ value is exclusive or not.
exclusiveMaxValue boolean Whether 'maxValue’ value is exclusive or not.
minLength integer Minimum permitted length of value for string types.
maxLength integer Maximum permitted length of value for string types.
length integer Field value length in number of bytes.
values [Value Object] List of possible values if the field is enumerated.
pattern string Regular expression to describe the pattern of the value for this field.
alwaysRequired boolean Boolean flag to indicate that this field is present in 100% of cases. Default: false
conditions [Condition Object] Field conditional requirements.
fields [Field Object] List of nested fields.

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Value

{
  "enum": 1,
  "description": "Client"
}

Description of an enumerated, valid value.

Field Name Type Description
enum string or number Required. Enumeration as it appears on the wire.
description string Required. Human-readable description of the intended value.
isDefault boolean Default value if the field is not provided.

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Condition

{
   "label": "PriceOnLimitOrder",
   "expressionType": "jsep",
   "expression": "($40 == 2)",
   "isReqd": true,
   "isAbsent": false
 }

In this example simple JavaScript expression is used to define the conditions. This condition defines that if value of tag 40 is 2, given fields is required.

Field conditional requirements.

Field Name Type Description
label string Required Name of the condition rule.
expressionType string Required Type of grammar used in expression field. Value MUST be "jsep".
expression string Required Condition expression. Below block matters if this expression evalualtes to true.
isReqd boolean Field is mandatory in such condition.
isAbsent boolean Field should not be present in such condition.
values [Value Object] List of valid values.

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Condition Expression Grammar

($40 == 2)
($40 == 3)  || ($40 == 4)
($40 == 2) && ($44 > 0)
($2_OrderQty > 100)

Currently, only supported expression type is jsep i.e. JavaScript expression.

In simple terms, it’s a conditional expression used in if statements which evaluates to true or false.

For tag values based APIs, value of the tag is expressed as: $<wireId> e.g. $40

For others e.g. native APIs, value of field is expressed as: $<position>_<name> e.g. $2_Price

Tokens that can be used in condition expression are:

  1. Comparison operators e.g. ==, >, etc.

  2. Logical operators e.g. &&, ||, etc.

  3. Brackets

Example

{
  "example": "8=FIX.4.2|9=69|5=A|34=12|49=SENDER|52=20140228-05:42:38.026|56=TARGET|98=0|108=120|10=238|",
  "description": "Market order example"
}

An example of the specified message.

Field Name Type Description
example string Required. Actual example.
description string Required. Description (or purpose) of the example.

Patterned Objects

Field Pattern Type Description
^x- Any Allows extensions to the FinSpec Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Workflows

The workflows section is an array of workflow objects defined as follow:

Field Name Type Description
name string Required. Name of the workflow.
description string Required. Description of the specific workflow being modeled
includeMessages [Array] Required. List of messages (wireId) included in the workflow
states [Array] Required. list of possible individual states the object (e.g. Orders, Quote) can take in the workflow
transitions [Array] Required. Description of transitions (including triggering event - FIX msg - and resulting state)

IncludeMessage

{
      "messageType": ["D","F","G","8"],
      "linkedBy": ["$11", "$41", "$37"]
}

The array consists of IncludeMessage objects defined by the following fields:

Field Name Type Description
messageType array Required. Comma-separated wireID corresponding to messages involved in this workflow
linkedBy array Field (wireID) that link all those messages together

State

{
    "ref": "Order.Acknowledged",
    "name": "Acknowledged",
    "isInitial": true,
    "description": "Unacknowledged, new order sent to target recipient"
}

The 'states’ array is a list of state objects which are defined by the fields below:

Field Name Type Description
ref string Required. Reference of the object state. It needs to be unique and will be used in the start and end fields
name string Name given to this specific state
isInitial boolean Is this an initial state? can not transition from any other state.
isFinal boolean Is this a final state? Can not transition to any further state.
description string Description of this specific state

Transition

{
    "description": "Cancellation of an open order",
    "start": ["Order.Acknowledged","Order.PartiallyFilled"],
    "triggerBy" : {
        "messageWireId": "F"
    },
    "responses": [
        {
            "messageWireId": "9",
            "where": {
                "expressionType": "jsep",
                "expression": "($150 == 4)&($39 == 0)"
              },
            "end": "Order.Acknowledged",
            "isSuccess": false
        },
        {
            "messageWireId": "9",
            "where": {
                "expressionType": "jsep",
                "expression": "($150 == 4)&($39 == 1)"
              },
            "end": "Order.PartiallyFilled",
            "isSuccess": false
        },
        {
            "messageWireId": "8",
            "where": {
                "expressionType": "jsep",
                "expression": "($150 == 4)&($39 == 4)"
              },
            "end": "Order.Closed",
            "isSuccess": true
        }
    ]
}

The 'transitions’ array is composed of 'transition’ objects which are defined by the fields below:

Field Name Type Description
description string Description of this transition
transitionStartstart Array Required. List of states the transition can iniate from.
triggerBytriggerBy [triggerBy Object] Sollicited message (Action) required to trigger the transition
responses [Array] Required. List of possible responses: messages with field conditions

triggerBy

Field Name Type Description
messageWireId string WireID of the message that trigger this transition

Response

Field Name Type Description
messageWireId string WireID of the response message
where [where Object] Specific field condition in the message
end string resulting state at the end of the transition
isSuccess boolean Did the transition successfully complete?

Where

Field Name Type Description
expressionType string Required Type of grammar used in expression field. Value MUST be "jsep".
expression string Required Condition expression. Below block matters if this expression evaluates to true.

Specification Validator

The FinSpec validator is a tool designed to validate that FinSpec JSON documents correctly match the specification as defined, or to return error messages indicating where the validation is failing.

Launch the server

  1. Install Node JS, if not done already. You can find installables here.

  2. Launch terminal and go to finspec-validator folder. Run the validator server using command:

node server.js

  1. Keep this sever running in background or foreground to be able to perform the validations.

How to validate

Version 1.0 (Current Version):

   curl -XPOST localhost:8080/validate?version=1.0 -F json=@./myschema-1.0.json
   {"pass":true,"message":"Good job!"}

Version 0.3 (Prior Version):

   curl -XPOST localhost:8080/validate?version=0.3 -F json=@./myschema-0.3.json
   {"pass":true,"message":"Good job!"}

Your schema can be validated using following command:

curl -XPOST localhost:8080/validate?version=<schema_version> -F json=@/path/to/finspec.json

Where, schema_version is target FinSpec schema version.