Tablature Overview
Traditionally, specifications are distributed as Word files, PDFs or web pages -- that is, as humanly readable documents. There are several problems with this approach.
- Text narratives are often vague and ambiguous. What is clear to an author is not clear to readers because they lack the context and background of the expert.
- Documents are not directly actionable or executable. Conversion to executables depends on humans interpretting documents into technical resources and code.
- Documents typically are not kept up to date with technical implementations. To update them requires time and money, and that effort may be considered lower priorty than getting software developed, and it is not always rewarded.
- A pitfall of rich document formats is getting hung up on style rather than substance. Time spent on page breaks, fonts, and indexing can detract from the quality of contents.
FIX Trading Community is responsible for the FIX standard. It is a membership organization composed of brokers, exchanges, banks, and technology providers. A continuing problem for counterparties in a trading relationship is the need to exchange their particular rules of engagement. Every firm is its own special sauce that is slightly different from another's messaging specification. Traditionally, that meant distributing documents as mentioned above to give the specifics of message structures and service behavior. Therfore,onboarding new customers was time consuming, expensive, and error prone.
Before we explain Tablature, we must introduce the first part of the solution, Orchestra. The first step to making actionable specifications is create a standard for exchanging machine readable rules of engagement.
Orchestra is a FIX standard to exchange rules of engagement as actionable data. Its file format is controlled by an XML schema, and thus it is machine readable. Tools can use an Orchestra file automatically generate code, configurations, test cases, and so forth.
Orchestra defines two XML schemas.
- The repository schema provides a standard for defining message structures and workflow. Workflow specification tells the possible responses to a message type and when each of them applies.
- The interfaces schema is used to define service offerings, including the protocol stack used for each exposed interface. Each service can be configured with an orchestration--a link to an Orchestra repository file. Additionally, sessions can be configured for services with their identifiers and technical configuration, such as host and port to connect to.
FIX Trading Community is developing a set of tools for members, including an Orchestra file editor called Orchid.
Orchestra is part of the solution to the fuzzy specification problem because machine readable data is precise and unambiguous. Also, we have developed documentation generators for Orchestra that turn the spec into a humanly readable ducument. So documentation can always be up to date whenever changes are made.
But that leaves the problem of creating a specification. Business analysts would like to author a set of message definitions, workflows, and service offerings without getting involved in the intricacies of XML or other technical methods. Users have requested an easier creation process.
Tablature was conceived as an easy authoring method. The main idea is this: a user just edits a document that captures humanly readable rules of engagement. But the document is semi-structured, not completely arbitrary. Then a tool can treat the document as data and extract information from it. It then translates it into a machine-readable file. In short, the specification is easy to author but at the same time it is actionable because it can be translated into a machine readable format.
Markdown has been selected as the document format for Tablature. It mainly consists of just plain text but with some very light symbols for simple formatting. This allows an author to mostly concentrate on contents.
You may use a dedicated markdown editor, of which there are many, or any plain text editor of your choice.
Tablature tools are bidirectional. One tool parses a text file in the markdown format and writes an Orchestra file in one of the two schemas described above. A companion tool performs the reverse operation, that is, Orchestra to markdown. A tool pair supports iterative development through a roundtrip cycle.
The tool pair for the Orchestra repository schema consists of md2orchestra and orchestra2md. (They probably should have been named with the word repository instead of Orchestra, but they were the first ones written.) See Tablature User Guide for Messages
The tool pair for the Orchestra interfaces schema consists of md2interfaces and interfaces2md. See Tablature User Guide for Interfaces