The FinSpec Specification
Welcome to the FinSpec Project!
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.
"Multi-protocol" here means that the variety of typical API formats found in this niche should be able to be supported by the protocol. For example, Financial Information Exchange (FIX), typical "native" formats offered by various different trading platforms such as ITCH and OUCH.
Our goals is to create a single document that is capable to be consumed by 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, accelerating development and reducing errors.
Why not OpenAPI or AsyncAPI?
FinSpec has been heavily inspired by the amazing work of the OpenAPI initiative (formerly Swagger), and of the more recent AsyncAPI initiative. It is not our intention to replicate or replace this work - in fact we offer our support to anyone in our community seeking to adopt these formats.
No - our goal is to extend the power of those concepts into existing protocols that dominate financial services today, most notably FIX. We all know that the complexity of financial services connectivity means that change happens slowly. Instead of waiting for the day REST replaces FIX, we are bringing the benefits of REST into the FIX world.
Why not QuickFIX or FIX Orchestra?
There are other formats available in this area, some of which are in the public domain.
The most common is the QuickFIX XML (sometimes referred to as the "data dictionary") used by the ubiquitous QuickFIX engine. While this format does an adequate job of capturing messages, fields and enumerations, this basic format is not designed to be read by humans at all; it was never designed for that.
FIX Orchestra is a format defined by the FIX Trading Community which - like FinSpec - aims to capture both descriptive information as well as API "mechanics" (fields, messages, enumerations, as well as the interactions between those objects). While FIX Orchestra is a good format, from it made sense for us to develop our own for a few key reasons, including:
- Use of JSON as opposed to XML (yuk!)
- The agility that comes from working outside of a "formal" standards body
- The focus that comes from concentrating on the 90% use case instead of having to handle edge cases requested by members
How can I get support?
Despite being supported by FixSpec - a commercial software vendor in the financial services API space - FinSpec is NOT intended to be a closed, proprietary or single-vendor protocol in any way.
We want FinSpec to flourish as an open format available to the whole industry (even our commercial competitors), and we are happy to offer our support and advice to anybody seeking to adopt or use the format.
Feel free to raise issues or make pull requests via these Github pages or reach out to us directly at [email protected].
Versioning
The current version of the FinSpec specification is 4.0.
To read more about the schema definition: Get Started.
FinSpec schema versions 3.x are no longer actively developed, but will be supported by FixSpec until the end of 2022. Earlier schema versions are no longer supported, and we do not recommend their use in production.
We would strongly recommend upgrading to 4.0 as soon as possible. Please contact [email protected] for (free) assistance to upgrade schema version.
Revision History
| Version | Date | Notes | Example | Guide |
|---|---|---|---|---|
| 4.0 | 2022-01-03 | Structure, definitions and UML support. | Link | Link |
| 3.0 | 2020-07-24 | Layout and Transform extensions. | Link | |
| 2.1 | 2019-01-18 | Update to workflow schema. | Link | Retired |
| 2.0 | 2018-06-27 | Support for navigation and history keys. Extended block (component) support. Retire 0.x versions. | Link, Link | Retired |
| 1.2 | 2018-02-14 | Support for machine readable bit fields. | Retired | |
| 1.1 | 2017-03-10 | Support for functional (context-specific) messages. | Retired | |
| 1.0 | 2017-02-28 | Enhanced protocol metadata, informational messages and change history. | Retired | |
| 0.3 | 2016-04-29 | Add support for finite state machine workflow. | Retired | |
| 0.2 | 2016-03-16 | Datatypes related enhancements. Added conditions block to field. | Retired | |
| 0.1 | 2016-01-06 | Initial release of FinSpec Specification. | Retired |
Schema Validation
FinSpec is a JSON schema, and therefore all FinSpec documents should be validated against the official schema to be considered "valid".
We STRONGLY recommend validating FinSpec schema validation prior to deployment or sharing with counterparties. You can find FinSpec Schema validator here.
License
Copyright 2022 FixSpec Limited
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.