Introduction

The goal of FinSpec is to define a standard, protocol-agnostic, machine-readable 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 2.0: To read more about the schema definition: [Get Started].

FinSpec schema versions in the 1.x series are still supported, but support for 0.x versions is now withdrawn. We would strongly recommend upgrading to 2.0 as soon as possible. Please contact happytohelp@fixspec.com for (free) assistance to upgrade schema version.

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
[2.0] 2018-06-27 Support for navigation and history keys. Extended block (component) support. Retire 0.x versions.
[1.2] 2018-02-14 Support for machine readable bit fields.
[1.1] 2017-03-10 Support for functional (context-specific) messages.
[1.0] 2017-02-28 Enhanced protocol metadata, informational messages and change history.
[0.3] 2016-04-29 Add support for finite state machine workflow.
[0.2] 2016-03-16 Datatypes related enhancements. Added conditions block to field.
[0.1] 2016-01-06 Initial release of FinSpec Specification.

Roadmap

We continuously look for ways to improve our schema and make it as practical and useful for our community.

If you are exploring using the schema for internal projects but are stuggling to model something, then please drop us a line. We would be happy to provide help and guidance, or even enhance the schema to accomodate your workflow.

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 v2.0

Change log

The major version has been incremented for this version of the FinSpec schema, in recognition of a various non backward-compatible changes to both naming conventions and JSON keying.

Move to JSON Schema 0.7

Things move on, and so we are too. Version 2.0 of the FinSpec schema is now written to comply with JSON Schema 0.7. For more information on the JSNO Schema, please visit http://json-schema.org/.

General Tightening & Tuning

The real value of machine-readable specifications comes from the fact that they are easier to swap and consume, but the value is decreased each time we allow things to be ambiguous or weakly-validated. So we’ve decided to tighten a few loose screws that could have allowed some things to otherwise fall through the cracks. In no particular order, these include:

Changes to re-usable field blocks (a.k.a. components)

{
    "blocks": {
        "header_key": {
            "name": "Standard FIX Header",
            "description": "The standard FIX message header",
            "fields": [...],
            "isHeader": true,
            "isTrailer": false
        },
        "footer_key": {
            "name": " Standard FIX Trailer",
            "description": "The standard FIX message trailer",
            "fields": [...],
            "isHeader": false,
            "isTrailer": true
        },
        "instrument_key": {
            "name": " Instrument Definition",
            "description": "The standard FIX message trailer",
            "fields": [...],
            "isHeader": false,
            "isTrailer": false
        },
        ...
    }
}

Prior versions of the FinSpec schema featured a CommonBlocks section which allowed the definition of re-usable component blocks. It was noted that the examples provided suggested that this use was limited to header and footer components exclusively. Since this constraint was never by design, v2.0 makes it clearer by renaming the commonBlocks object to simply blocks, in recognition that a block may not appear in every single message, and is therefore not always “common”.

The blocks object remains a keys-JSON object, where the key is any unique string to represent the block to be described (not limited to “header” and “footer” as suggested in peiord versions).

Two new boolean attributes of isHeader and isTrailer have been added to the FieldSet Object to allow header and trailer (footer) components to be programmatically found within a larger array of components.

Support for navigation

"nav": {
    "info": {
        "General": {
            "items": [
                {
                    "key": "CV8c3AAn",
                    "name": "Contacts"
                },
                ...
            ]
        },
        ...
    },
    "technical": {
        "Session": {
            "items": [...]
        },
        ...
    },
    ...
}

Message grouping and presentation is of general interest when documenting a specification. The new, optional Navigation section allows authors to capture the intended layout and grouping of messages for display purposes, including the definition of multi-level menus.

The navigation elements link to message elements via the key attribute.

Keyed JSON in message lists

{
    "messages": {
        "technical" : {
            "uZYkCoa5" : {
                "name": "Logon",
                "wireId": "A",
                "description": "Use this message to connect to the counterparty",
                "fields": [...],
                "isSession": true,
                "historyKey": "d320sMwm"
            },
            "EzU2NBX9" : {
                "name": "Logout",
                "wireId": "5",
                "description": "Use this message to disconnect from the counterparty",
                "fields": [...],
                "isSession": true,
                "historyKey": "f540sMxx"
            }        
        }
    }
}

In prior versions of the schema, messages were presented as a simply array of Message objects. With the introduction of the nav which features a unique reference key, we have taken the opportunity to convert this into a keyed JSON object, allowing applications to make a direct link between a nav item and the relevant message.

In addition, functional views have a new baseKey to point to the technical message upon which they are based.

Collapse of Session and Application messages

{
    "messages": {
        "info": { ... },
        "technical" : { ... },
        "functional" : { ... }
    }
}

In prior versions of the schema, technical messages were divided between session and application messages. In v2.0 we are replacing this approach with a common technical messages block (thus aligning to the new nav constructions, and introducing a new isSession boolean within Message objects.

Rename blockId to blockKey

We have slightly changed the way Field objects point to blocks. The blockId attribute has been renamed blockKey, to bring greater naming consistency.

Addition of new historyKey

Finally, we have added a new historyKey attribute to the Message object, providing applications with a unique key with which to link messages across spec versions.

For example, supposed we introduce a new “RedAlgoOrder” message in version 10 of a specification, then we would assign this a unique historyKey value of “abcedf” (we recommend using a simple random string for this purpose). Suppose in version 11 of the specification we decide to rename our message to “BlueAlgoOrder”. Well, if the message is consistently stamped with a historyKey of “abcdef”, then all applications should be able to link these two message objects together and therefore understand the change.

Format

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.
nav Nav Optional
A proposed UI navigation structure for the API specification.
blocks Blocks 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 WorkflowsArray 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",
    "status": "FINAL",
    "logo": "https://fixspec.com/images/fixspec.jpg",
    "contacts": [...]
}

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.
status string Optional [New in 2.0]
A description of the current state of this specification (eg DRAFT or FINAL).

The Info object may contain vendor extensions.

Contacts

{
    "contacts": [
        {
            "name": "Customer Services",
            "email": "happytohelp@fixspec.com",
            "url": "https://fixspec.com"
        },
        ...
    ]
}

An array of contact information for the specification. Each specification must contain at least one piece of contact information.

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 See note below
The version number of the immediately prior spec version (i.e. the starting spec to which changes have been applied).
lastVersionDate string See note below
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.

NOTE: At least one of lastVersion and lastVersionDate must be present.

The Changes 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

{
    "datatypes:": [
        {
            "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 string 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", "ascii", "uint8", "int8", "uint16", "int16", "uint32", "int32", "uint64", "int64", "float", "double"
description string Required
Description/remark for 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 ExamplesArray Optional
Array of examples to explain the datatype.

The Datatype object may contain vendor extensions.

{
    "nav": {
        "info": {
            "General": {
                "items": [
                    {
                        "key": "info_item_unique_key",
                        "name": "Information section header"
                    },
                    ...
                ]
            },
            ...
        },
        "technical": {
            "Session": {
                "items": [...]
            },
            ...
            "Order Entry": {
                "items": [...]
            },
            ...
        },
        "block": {
            "Core": {
                "items": [...]
            },
            ...
        }
    }
}

The new navigation object allows the capture of intended UI navigation for a specification; how the author intended messages and information sections to be logically grouped for display. Think of it as the electronic equivalent of a Table Of Contents.

The top-level nav object may have up to four sections (but a minimum of one), relating to various content types: info, blocks, technical and functional.

Each of these sections may have as many sub-menus as required, with each sub-menu represented as a keyed JSON fragment. In the example here, “Session” and “Order Entry” are considered sub-menus of the technical type.

At the end nodes of this heirarchy should be a NavItemsArray (items) array, which is a simple array containing references to the relevant information section, block or fieldset. The definition of the end-node NavItems contains the unique key for the detail to be displayed, the same unique key used for keying the section or fieldset in the relevant JSON section allowing the navigation and detail to be linked together.

Field Name Type Description
name string Required
Name of the section or fieldset.
key string Required
Unique key linking for the information section or fieldset. Links to the key found in the relevant blocks or messages object.

Both the (top-level) Navigation object and the (lowest-level) NavItemsArray objects may contain vendor extensions.

Blocks

NOTE Structure has changed under v2.0.

{
    "blocks": {
        "block_1": {
            "name": "Standard FIX Header",
            "description": "The standard FIX message header",
            "historyKey": "block_1_hist",
            "isHeader": true,
            "isTrailer": false,
            "fields": [...]
        },
        "block_2": {
            "name": "Standard FIX Trailer",
            "description": "The standard FIX message trailer",
            "historyKey": "block_2_hist",
            "isHeader": false,
            "isTrailer": true,
            "fields": [...]
        },
        "block_3": {
            "name": "Instrument",
            "description": "Re-used instrument identifier block",
            "historyKey": "block_3_hist",
            "isHeader": false,
            "isTrailer": false,
            "fields": [...]
        },
        ...
    }
}

A list of re-useable blocks (or components) used in the messages in the API specification. From FinSpec Schema v2.0, this is a keyed JSON fragment, with each block’s key being a unique reference to that block for reference in other fieldsets. While we recommend using random keys here, your implementation may allow other keys such as slugged names. Each block (eg block_1 in the example here) represents a FieldSet.

IMPORTANT It is NOT assumed that these JSON keys are maintained across specification versions; for example if you choose to set the key equal to a slugged name then this key will “break” should you ever change the block name. For this reason, the historyKey attribute is used to maintain a consistent identifier across specification versions. It is historyKey and not JSON key that should therefore be used in comparison logic.

The Blocks object may not contain vendor extensions.

Messages

{
    "messages": {
        "info": {
            "info_1" : {
                "name": "Symbology",
                "description": "This is some text description of symbology demanded by the recipient.",
                "historyKey": "info_1_hist"
            },
            ...
        },
        "technical": {
            "technical_1": {
                "name": "Logon",
                "wireId": "A",
                "description": "The Logon message authenticates a user establishing a connection to a remote system.",
                "fields": [...],
                "isSession": true,
                "direction": "both",
                "historyKey": "technical_1_hist"
            },
            ...
        },
        "functional": {
            "functional_1": {
                "name": "VWAP Order",
                "wireId": "D",
                "description": "The new order message type targeting the VWAP algorithmic strategy.",
                "fields": [...],
                "historyKey": "functional_1_hist",
                "baseKey": "technical_3",
                "context": {...},
                "examples": [...]
            },
            ...
        }
    }
}

A list of all messages used in the API specification.

The section can be used to carry up to three types of message - info sections, technical messages, and functional views, where a functional view is a techncial message within a specific business context.

Field Name Type Description
info InfoSection See note below
Series of free-text, descriptive sections which do not directly relate to messaging e.g. Symbology, Market Phases etc.
technical Fieldset See note below
List of session and application-level e.g. Logon, Heartbeat, etc.
functional FieldsetWithContext Optional
List of functional messages, describing technical messages within a given context.

NOTE In order to pass validation, a specification must contain either the info or technical sections (or both).

For those upgrading from 1.x schema versions, note that the session and application blocks have now been removed in favour of a single technical block, combined with a new isSession attribute at the individual message level. Note also that the JSON messages lists within a given block are keyed JSON fragments, as opposed to simple arrays under 1.x.

The Messages object may contain vendor extensions.

Info Section [New in 2.0]

{
    "name": "Symbology",
    "description": "<p>The symbology used on our venue is ...",
    "historyKey": "unique_history_key"
}

An informational section used to convey specification data unrelated to messages. Example usage may include descriptions of symbology, connectivity approach or hours of operation.

Field Name Type Description
name string Required
Name (header) of the section.
description string Required
HMTL or plain text.
historyKey string Optional [New in 2.0]
Unique, persistent key suitable for linking an information section across versions.

The InfoSection object may contain vendor extensions.

Fieldset [Renamed in 2.0]

{
    "name": "NewOrderSingle",
    "wireId": "D",
    "direction": "in",
    "description": "...",
    "fields": [...],
    "historyKey": "unique_history_key",
    "isSession": false,
    "examples": [...]
}

A list of attributes collectively used to describe a fieldset (either a re-used block or a technical message) in the specification.

Field Name Type Description
name string Required
Name of the message.
wireId string or integer Required (except blocks)
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.
historyKey string Optional [New in 2.0]
Unique, persistent key suitable for linking a fieldset across versions.
isSession boolean Optional [New in 2.0]
Boolean to indicate whether this fieldset relates to session-level connectivity. Default is false.
isHeader boolean Optional [New in 2.0]
Boolean to indicate whether this fieldset represents a common header block. Default is false.
isTrailer boolean Optional [New in 2.0]
Boolean to indicate whether this fieldset represents a common trailer block. Default is false.
fields Field Required
List of fields available within a message.
examples ExamplesArray Optional
List of message examples.

The Fieldset object may contain vendor extensions.

FieldsetWithContext [Renamed in 2.0]

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

A functional view describes a message within a particular business context. Common use cases for functional views include: - Views differenting state (eg Order Acknowledgement vs Execution) - Views differenting order types (eg Limit Order vs VWAP) - Views differenting asset class (eg Spot FX Order vs FX Forward Order)

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.
baseKey string Optional [New in 2.0]
The unique key given to the technical message upon which this functional view is based.
historyKey string Optional [New in 2.0]
Unique, persistent key suitable for linking a fieldset across versions.
context Context Required
Digital description of the intended message context.
fields Field Required
List of fields available within a message.
examples ExamplesArray Optional
List of message examples.

The FieldsetWithContext 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, javascript 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

{
    "fields": [
        {
            "position": 0,
            "name": "Header",
            "description": "Standard FIX header",
            "blockKey": "header_block_key",
        },
        {
            "position": 1,
            "name": "ClearingAccount",
            "description": "Clearing Account Type",
            "datatype": "uint8",
            "length": 1,
            "values": [
                {
                    "wireValue": 1,
                    "description": "Client"
                },
                {
                    "wireValue": 3,
                    "description": "House"
                }
            ]
        },
        {
            "position": 2,
            "name": "Price",
            "alwaysRequired": false,
            "conditions": [...],
            "description": "Price per share",
            "wireId": "44",
            "datatype": "Price"
        },
        ...
    ]
}
{
    "fields": [
        ...,
        {
            "offset": 12,
            "name": "OrderInst",
            "description": "Order instructions bit field",
            "datatype": "uint8",
            "bits": [
                {
                    "offset": 0,
                    "width": 1,
                    "name": "LocateReqd",
                    "values": [
                        {
                            "wireValue": 0,
                            "description": "No Locate required"
                        },
                        {
                            "wireValue": 1,
                            "description": "Locate required"
                        }
                    ]
                },
                ...
            ]
        },
        ...
    ]
}

Array of fields to be present in a given fieldset (message or block).

Each field entry takes one of two forms: - A reference to a block defined elsewhere using the blockKey reference, or - An individual field defined in the fieldset.

IMPORTANT Re-used header and trailer blocks MUST be explicitly referenced within fields arrays just like any other block. There is no “assumption” of their presence based on protocol. (This requirement allows FinSpec to support the definition of multiple header / trailer blocks, with flexibility for authors to indicate the correct choice for a given fieldset).

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 Required for tag-value protocols
Wire identifier for the field (eg tag 35 in FIX).
blockKey string Required for blocks [New in 2.0]
The unique reference for the block from the blocks section.
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 EnumArray 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 ConditionArray Optional
Field conditional requirements.
fields Field Optional
List of nested fields, indicating a repeating group under the current field.
bits BitArray Optional
Details about how bits are organized if this is a bit field.

The Field object may contain vendor extensions.

Enum Array [Renamed in 2.0]

{
    "values": [
        {
            "wireValue": 1,
            "name": "Client",
            "description": "This is a long description",
            "isDefault": true
        },
        ...
    ]
}

A simple array of permitted enumerations for this field / bit field.

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 EnumArray object may contain vendor extensions.

BitsArray [Renamed in 2.0]

{
    "bits": [
        {
            "offset": 0,
            "width": 1,
            "name": "LocateReqd",
            "values": [
                {
                    "wireValue": 0,
                    "description": "No Locate required"
                },
                ...
            ]
        },
        ...
    ]
}

A simple array of bits within a field.

NOTE Where observed, the “parent” field is expected to have a datatype with an isBitfield value of true. If this is not the case, then the bits array should be ignored, and the parent should be treated as a non-bitfield field.

Field Name Type Description
offset integer Required
Bit offset within a bit field indicating start of bits group.
width integer Required
Width of bits group in terms of numer of bits.
name string Required
Name of the bits group.
description string Optional
Description of the purpose and use of the bits group.
values EnumArray Optional
List of possible values for this bits group.

The BitsArray object may contain vendor extensions.

ConditionArray [Renamed in 2.0]

{
    "conditions": [
        {
            "label": "PriceOnLimitOrder",
            "expressionType": "groovy",
            "expression": "($40 == 2)",
            "isReqd": true,
            "isAbsent": false
        },
        {
            "label": "NoPriceOnMarketOrder",
            "expressionType": "groovy",
            "expression": "($40 == 1)",
            "isReqd": false,
            "isAbsent": true
        },        
        ...
    ]
}

A simple array of conditions, each of which should be evaluated in turn and the loop exited when the first evaluates to true. See below for a description of condition grammer.

NOTE In order for conditions to be examined, alwaysRequired should be set to false on the parent field, to avoid the parent field always being considered mandatory.

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 EnumArray Optional
List 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.

ExamplesArray

{
    "examples": [
        {
            "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"
        },
        ...
    ]
}

A simple array of examples associated with the fieldset. 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 ExampleArray object may contain vendor extensions.

WorkflowsArray [Renamed in 2.0]

{
    "workflows": [
        {
            "name": "Order entry workflow",
            "description": "This workflow describes expected behaviour for order entry",
            "includeMessages": [...],
            "states": [...],
            "transitions": [...]
        },
        ...
    ]
}

The workflows array section is a simple array of workflow objects, each defined as follows:

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

The WorkflowsArray object may not contain vendor extensions.

IncludeMessageArray [Renamed in 2.0]

{
      "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.

StateArray [Renamed in 2.0]

{
    "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.

TransitionArray [Renamed in 2.0]

{
    "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.2

Change log

Support for machine readable bit fields

Most binary specifications use bit fields to compress multiple parameters in single or multiple bytes instead of defining them separately thus saving space.

In prior versions of the schema, bit fields could be defined and described but were not machine readable i.e. couldn’t be read and processed programatically.

Version 1.2 adds a bit object, allowing bits within bit field to be defined as an array of bit object. Bit field can either define each bit defined separately or bits can be grouped togther, as shown in the example.

{
  "position": 12,
  "name": "OrderInst",
  "description": "Order instructions bit field",
  "datatype": "uint8",
  "bits": [
      {
        "offset": 0,
        "width": 1,
        "name": "LocateReqd",
        "values": [
          {
            "wireValue": 0,
            "description": "No Locate required"
          },
          {
            "wireValue": 1,
            "description": "Locate required"
          }
        ]
      },
      {
        "offset": 1,
        "width": 3,
        "name": "OrderCapacity",
        "values": [
          {
            "wireValue": 1,
            "description": "Agency"
          },
          {
            "wireValue": 2,
            "description": "Principal"
          },
          {
            "wireValue": 3,
            "description": "Riskless Principal"
          }
        ]
      }
    ]
  }

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": [
      {
          "wireValue": 1,
          "description": "Client"
      },
      {
          "wireValue": 3,
          "description": "House"
      }
  ]
}
{
  "position": 25,
  "name": "Price",
  "alwaysRequired": false,
  "description": "Price per share",
  "wireId": "44",
  "datatype": "Price"
}
{
  "position": 12,
  "name": "OrderInst",
  "description": "Order instructions bit field",
  "datatype": "uint8",
  "bits": [
      {
        "offset": 0,
        "width": 1,
        "name": "LocateReqd",
        "values": [
          {
            "wireValue": 0,
            "description": "No Locate required"
          },
          {
            "wireValue": 1,
            "description": "Locate required"
          }
        ]
      },
      {
        "offset": 1,
        "width": 3,
        "name": "OrderCapacity",
        "values": [
          {
            "wireValue": 1,
            "description": "Agency"
          },
          {
            "wireValue": 2,
            "description": "Principal"
          },
          {
            "wireValue": 3,
            "description": "Riskless Principal"
          }
        ]
      }
    ]
  }

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.
bits Bit Optional
Details about how bits are organized if this is a bit 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.

Bits

{
  "offset": 0,
  "width": 1,
  "name": "LocateReqd",
  "values": [
    {
      "wireValue": 0,
      "description": "No Locate required"
    },
    {
      "wireValue": 1,
      "description": "Locate required"
    }
  ]
}

Description of a bits group within a bit field.

Field Name Type Description
name string Required
Name of the bits group.
description string Optional
Description of the purpose and use of the bits group.
offset integer Required
Bit offset within a bit field indicating start of bits group.
width integer Required
Width of bits group in terms of numer of bits.
values Values Optional
List of possible values for this bits group.

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

Specification Validator

The FinSpec validator is an open-source 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.

Grab a copy at https://github.com/finspec/finspec-validator