search

FIXTradingCommunity / tablature

Easy authoring for rules of engagement using markdown
https://www.fixtrading.org/
Apache License 2.0
11 stars 8 forks source link

[orchestra2md] Compact representation of code sets in markdown #48

Open kleihan opened 3 years ago

kleihan commented 3 years ago

Currently, fields and codesets are provided in the markdown file as separate chapters. This is fit for purpose for the complete FIX standard but less so for a given implementation, typically a small subset.

The current markdown output also fits the authoring requirement for markdown very well and should continue to be the standard. The requirement is different when the markdown file is used for a Rules of Engagement document (docx, pdf, html). A spec reader would like to have the following information directly integrated into the message/component/group table.

The majority of publicly available RoE docs integrate this information. It does not require to switch back and forth between chapters. FIXimate supports it albeit in a different way by integrating supported values into the field description in the data dictionary and displaying that below the message layout.

Field definition descriptions are separate from field usage descriptions, i.e. the compact representation would not contain field definition text in the message/component/group tables. The entire sections for fields and codesets are then obsolete unless they also need to be described in general.

A field usage entry in markdown in a compact representation should look as follows for LocateReqd(114) in NewOrderSingle(35=D):

Required for short sell orders

Supported values: N = Indicates the broker is not required to locate Y = Indicates the broker is responsible for locating the stock

The CR/LF should use "/P/" as usual for the multiline text. The datatype of the field (Boolean, not LocateReqdCodeSet) should be an extra column for all fields, i.e. also those that do not have a codeset, for example:

Tag Name Type Presence Documentation
114 LocateReqd Boolean N [see above]

The power of this compact representation comes when using codeset scenarios. You can then immediately see which values of a field are supported in which message.

donmendelson commented 3 years ago

The logic to output inline codes has been implemented, but it needs a command line switch to activate it.