Dictionaries API

The DictionaryJSON data contract and its runtime index, structural validation, and the FIXT.1.1 transport/application pair with its runtime merge. Generated from @boarteam/fix 0.5.2 as installed; the doc text is the library’s own. Guide: Choosing a dictionary.

DictionaryJSONinterfacesince 0.1.0

interface DictionaryJSON

Source: packages/fix/src/dictionary/types.ts:176

The complete, serializable dictionary.

```
version: string
```
Dialect identifier, e.g. "FIX.4.4" or "FIX.5.0SP2". For pre-FIXT dialects this matches the BeginString (tag 8) value; for FIXT dialects it names the application version, which differs from the transport's beginString ("FIXT.1.1") — the app version rides on DefaultApplVerID(1137) / ApplVerID(1128), see applVerID.
```
beginString: string
```
The BeginString (tag 8) value framed messages must carry, e.g. "FIX.4.4".
```
applVerID?: string
```
The ApplVerID enum code (tag 1128 / DefaultApplVerID 1137 value) identifying this dictionary's application version under FIXT, e.g. "9" for FIX 5.0 SP2. Present only on FIXT-era application/merged dictionaries; absent for pre-FIXT dialects (whose app version is implied by the BeginString) and for transport-only dictionaries.

source?: {
    generator: string;
    spec: string;
    generatedFrom?: string;
}

Provenance: what generated this dictionary and from what source.

```
datatypes: Record<string, DataTypeDef>
```
Datatypes by name.
```
fields: Record<number, FieldDef>
```
Fields by numeric tag.

components: Record<string, ComponentDef>

Components by name.

```
messages: MessageDef[]
```
Messages, in spec order.
```
coverageGaps?: CoverageGap[]
```
Known limitations of this generated dictionary.
```
extensions?: string[]
```
Provenance of applied extensions: the id of every extension declaration merged into this dictionary by extendDictionary, in application order. Absent on pristine generated dictionaries.

Dictionaryclasssince 0.1.0

class Dictionary

Source: packages/fix/src/dictionary/Dictionary.ts:21

A runtime index over a DictionaryJSON: fast lookup of fields, messages, and components, plus the derived structure the codec needs — repeating-group delimiters, component expansion, and per-message allowed-tag sets.

The instance is immutable and holds a reference to the original JSON (exposed via json); all derived data is computed lazily and memoised. Construct one with loadDictionary.

```
readonly json: DictionaryJSON
```
The underlying data this index was built from.
```
constructor(json: DictionaryJSON)
```
Build the index over json. Prefer loadDictionary, which reads better at call sites.
```
get version(): string
```
Dialect identifier, e.g. "FIX.4.4".
```
get beginString(): string
```
The BeginString (tag 8) value framed messages carry.
```
get applVerID(): string | undefined
```
The ApplVerID code (tag 1128 / DefaultApplVerID 1137 value) of this dictionary's application version under FIXT (e.g. "9" for FIX 5.0 SP2), or undefined for pre-FIXT and transport-only dictionaries. See DictionaryJSON.applVerID.

fieldByTag(tag: number): FieldDef | undefined

Look up a field by tag.

fieldByName(name: string): FieldDef | undefined

Look up a field by its spec name.

messageByMsgType(msgType: string): MessageDef | undefined

Look up a message by its MsgType value.

messageByName(name: string): MessageDef | undefined

Look up a message by its spec name.

component(name: string): ComponentDef | undefined

Look up a component by name.

datatype(name: string): DataTypeDef | undefined

Look up a datatype by name.

```
resolveDatatype(name: string): ResolvedDatatype | undefined
```
Resolve a datatype name to the coercion-relevant facts the codec needs: the transitive BaseType root plus the derivation-chain flags that change how a value is read (Boolean char, the space-delimited list of MultipleValueString, length-prefixed data). Walks the parent chain with a cycle guard so it is safe on an untrusted dictionary, and memoises per datatype name.
```
isGroupCounter(tag: number): boolean
```
Whether a tag heads a repeating group (its datatype is NumInGroup).
```
groupDelimiterTag(group: GroupMember): number | undefined
```
The delimiter (first) field tag of a repeating group: the tag that opens each entry on the wire. Resolved by walking the group body in order — descending into a leading component, or returning a leading nested group's counter — since FIX has no explicit group delimiters and the parser keys entry boundaries off this tag.
```
allowedTags(msgType: string): ReadonlySet<number>
```
The set of every field tag that may legitimately appear in a message, including group counters and all fields reachable through nested components and groups (and the standard header/trailer, which the message lists as components).
Memoised per message name. Returns an empty set for an unknown message.

loadDictionaryfunctionsince 0.1.0

function loadDictionary(json: DictionaryJSON): Dictionary

Source: packages/fix/src/dictionary/Dictionary.ts:274

Build a Dictionary runtime index from its JSON form. Does not validate the JSON; run validateDictionary first if the source is untrusted.

Parameter	Type	Description
json	DictionaryJSON	The dictionary data to index.

Returns Dictionary — The immutable runtime index over json.

validateDictionaryfunctionsince 0.1.0

function validateDictionary(json: DictionaryJSON): FixIssue[]

Source: packages/fix/src/dictionary/validateDictionary.ts:19

Structurally validate a DictionaryJSON: every reference resolves, every field has a known datatype and a valid tag, datatype bases are real roots, group counters are real counter fields with a resolvable delimiter, enum values are unique, and the datatype derivation tree is acyclic. Returns a (possibly empty) list of FixIssues — it never throws, even on a corrupt/untrusted object missing whole collections, so it is safe to run as the gate before loadDictionary. An empty result means the dictionary is internally consistent and safe to load.

This checks internal consistency, not conformance to any particular FIX version.

Parameter	Type	Description
json	DictionaryJSON	The dictionary object to check; arbitrary malformed input is tolerated.

Returns FixIssue[] — The internal-consistency findings; empty means safe to load.

FixtDictionariesinterfacesince 0.4.0

interface FixtDictionaries

Source: packages/fix/src/dictionary/fixt.ts:33

FIXT support: the transport/application dictionary pair.

Under FIXT.1.1 the session protocol and the application version split: tag 8 carries FIXT.1.1 while the application version rides on DefaultApplVerID(1137) (Logon) and the optional per-message header override ApplVerID(1128). This module gives the engine that split as data: a FixtDictionaries pair every codec entry point accepts alongside a plain dictionary, a runtime mergeFixtDictionaries (the documented-lossy convenience that produces a self-contained single dictionary, mirroring what the codegen does for @boarteam/fix-dict-fix50sp2), and the resolved per-pair machinery the codec uses internally (merged view + envelope tag set for layer attribution).

Design stance (matching the engine's "pure, dictionary-driven, non-throwing" rules):

No session state. DefaultApplVerID is an input on the pair, never remembered from a parsed Logon.
Parsing/encoding run over the merged view — structurally, a FIXT message is its app body wrapped in the transport envelope, and the merged dictionary is exactly that union (admin MsgTypes never collide with app ones).
Validation adds layer attribution on top of the merged verdict: every issue is tagged session (transport-owned: admin messages, envelope fields) or application, so callers can choose between a session Reject(3) and a BusinessMessageReject(j).

```
transport: Dictionary | DictionaryJSON
```
The transport (session) dictionary — FIXT.1.1 envelope + admin messages.
```
app: Dictionary | DictionaryJSON
```
The application dictionary. Either an application-layer dictionary (envelope-less messages — they are wrapped with the transport envelope at merge time) or a self-contained merged dictionary like @boarteam/fix-dict-fix50sp2 (used as-is).
```
resolveApp?: (applVerID: string) => Dictionary | DictionaryJSON | undefined
```
Optional multi-version resolver (the QuickFIX/J DataDictionaryProvider model): maps an ApplVerID code (per-message tag 1128, falling back to defaultApplVerID) to the application dictionary for that version. Return undefined to fall back to app.
```
defaultApplVerID?: string
```
The session's DefaultApplVerID(1137) — a caller-supplied input (the engine holds no session state). Used only to route resolveApp when a message carries no per-message ApplVerID(1128).

isFixtDictionariesfunctionsince 0.4.0

function isFixtDictionaries(d: Dictionary | DictionaryJSON | FixtDictionaries): d is FixtDictionaries

Source: packages/fix/src/dictionary/fixt.ts:62

Whether a dictionaries argument is the FIXT transport/app pair form.

Parameter	Type	Description
d	Dictionary \| DictionaryJSON \| FixtDictionaries	The dictionaries argument any codec entry point accepts.

Returns d is FixtDictionaries — Whether d is the FIXT transport/application pair form.

mergeFixtDictionariesfunctionsince 0.4.0

function mergeFixtDictionaries(transport: Dictionary | DictionaryJSON, app: Dictionary | DictionaryJSON): DictionaryJSON

Source: packages/fix/src/dictionary/fixt.ts:190

Merge a FIXT transport dictionary with an application dictionary into one self-contained DictionaryJSON — the runtime counterpart of the codegen merge that produces @boarteam/fix-dict-fix50sp2, exported for venue-dialect composition (mergeFixtDictionaries(fixt11, myAppLayerDialect)).

Semantics:

Identity: beginString from the transport (FIXT.1.1); version/applVerID from the app side (the app names the application version).
Catalogs unioned: fields (identity facts must agree — a contradiction throws; lengthField/enum knowledge unioned, transport-preferred), datatypes and components (must be identical where shared — a contradiction throws).
Messages: app messages that lack an envelope (application-layer dictionaries) are wrapped with the transport's header/trailer refs; already-enveloped ones (a merged dict passed as the app side) are kept as-is. On a MsgType collision the transport's definition wins and the app's duplicate is dropped (the session set is transport-owned), which makes the merge idempotent over an already-merged app side.

"Lossy" refers to the layering, not the data: the merged form cannot attribute a field to the session vs application layer any more — use the FixtDictionaries pair with validate for layer-attributed diagnostics.

Parameter	Type	Description
transport	Dictionary \| DictionaryJSON	The FIXT.1.1 session dictionary — envelope plus admin messages.
app	Dictionary \| DictionaryJSON	The application dictionary; envelope-less messages are wrapped with the transport’s header/trailer.

Returns DictionaryJSON — A fresh, self-contained merged DictionaryJSON.

FieldDefinterfacesince 0.1.0

interface FieldDef

Source: packages/fix/src/dictionary/types.ts:64

A FIX field definition, keyed by its numeric tag in DictionaryJSON.fields.

```
tag: number
```
The field's numeric tag.
```
name: string
```
The field's spec name, e.g. "Side". Unique across the dictionary.
```
type: string
```
The DataTypeDef.name of this field's datatype.
```
enumValues?: EnumValue[]
```
Allowed values, when the field is enumerated (its ## Valid values table).
```
isGroupCounter?: boolean
```
true when this field's datatype is NumInGroup — i.e. it heads a repeating group. Mirrored here so the runtime need not resolve the datatype to detect counters.
```
lengthField?: number
```
For a length-prefixed data field (datatype base data), the tag of the Length field that carries this field's byte count and immediately precedes it on the wire (e.g. RawData 96 → lengthField 95). The parser needs this to read a data value whose payload may itself embed the SOH separator. Absent for non-data fields.
```
description?: string
```
Original prose description from the spec.

DataTypeDefinterfacesince 0.1.0

interface DataTypeDef

Source: packages/fix/src/dictionary/types.ts:31

A FIX datatype (e.g. Price, UTCTimestamp, month-year). Datatypes form a derivation tree rooted at the five BaseTypes; base is the transitive root that determines wire coercion, while parent preserves the immediate edge.

```
name: string
```
The datatype name exactly as the spec writes it, e.g. "Price", "month-year".
```
base: BaseType
```
The transitive root primitive, which drives value coercion/validation.
```
parent?: string
```
Immediate parent in the derivation tree; absent for the five roots.
```
formatPattern?: string
```
Human format hint, e.g. "YYYYMMDD-HH:MM:SS[.sss]"; present for date/time types.
```
lengthPrefixed?: boolean
```
true for data: the value is preceded by a Length field and may embed SOH.
```
multiValueDelimiter?: string
```
The token delimiter for a list-valued datatype (" " for MultipleValueString). Absent for single-valued datatypes. The value is the delimiter, not a flag.
```
description?: string
```
Original prose description from the spec.

ResolvedDatatypeinterfacesince 0.1.0

interface ResolvedDatatype

Source: packages/fix/src/dictionary/Dictionary.ts:243

The coercion-relevant facts about a datatype, resolved from its derivation chain by Dictionary.resolveDatatype. Drives how the codec reads a raw wire value.

```
base: BaseType
```
The transitive root primitive that determines value coercion.
```
isBoolean: boolean
```
true when the datatype derives from Boolean (Y/N → true/false).
```
multiValueDelimiter?: string
```
The list separator when the datatype is multi-valued (" " for MultipleValueString).
```
lengthPrefixed: boolean
```
true for data: the value is length-prefixed and may embed the SOH separator.

EnumValueinterfacesince 0.1.0

interface EnumValue

Source: packages/fix/src/dictionary/types.ts:52

One allowed value of an enumerated field.

```
value: string
```
The on-the-wire value, verbatim and opaque ("1", "004", "AB").
```
name: string
```
A code-identifier-safe name derived from description (e.g. "Buy").
```
description: string
```
The spec's human description of this value.

ComponentDefinterfacesince 0.1.0

interface ComponentDef

Source: packages/fix/src/dictionary/types.ts:137

A reusable component block (e.g. Instrument, Standard Message Header).

```
name: string
```
The component's spec name, e.g. "Instrument".
```
members: MemberRef[]
```
The ordered members of the component.

MessageDefinterfacesince 0.1.0

interface MessageDef

Source: packages/fix/src/dictionary/types.ts:148

A FIX message definition.

```
name: string
```
The message's spec name, e.g. "Logon".
```
msgType: string
```
The MsgType value (tag 35), case-sensitive ("A", "a", "AB").
```
category: MessageCategory
```
Session (admin) vs application (app) message.
```
members: MemberRef[]
```
The ordered members, including the leading Standard Message Header and trailing Standard Message Trailer component references exactly as the spec lists them.

MessageCategorytypesince 0.1.0

Source: packages/fix/src/dictionary/types.ts:145

A message's session category. admin = session-level; app = application-level.

admin
app

MemberReftypesince 0.1.0

type MemberRef = FieldMember | ComponentMember | GroupMember

Source: packages/fix/src/dictionary/types.ts:134

A member of a message, component, or group body.

FieldMemberinterfacesince 0.1.0

interface FieldMember

Source: packages/fix/src/dictionary/types.ts:90

A plain field reference within a message, component, or group body.

```
kind: 'field'
```
Discriminant: a plain field reference.
```
tag: number
```
The referenced FieldDef.tag.
```
reqd: Reqd
```
Whether the field is required in this context.

ComponentMemberinterfacesince 0.1.0

interface ComponentMember

Source: packages/fix/src/dictionary/types.ts:100

A reference to a reusable component block; the runtime expands it in place.

```
kind: 'component'
```
Discriminant: a component reference.
```
name: string
```
The referenced ComponentDef.name.
```
reqd: Reqd
```
Whether the component is required in this context.

GroupMemberinterfacesince 0.1.0

interface GroupMember

Source: packages/fix/src/dictionary/types.ts:115

A repeating group: a NumInGroup counter field (counterTag) followed by as many repetitions of members as the counter's wire value declares. The delimiter (first) field is not stored — the runtime resolves it by walking members (through any leading component).

```
kind: 'group'
```
Discriminant: a repeating group.
```
counterTag: number
```
The counter field's tag (a NumInGroup field).
```
reqd: Reqd
```
Whether the group is required in this context.
```
members: MemberRef[]
```
The ordered body of one group entry; may itself contain components and groups.
```
bodyFromCanonical?: boolean
```
true when this group's body was not present inline in the spec source and was filled from the canonical body for counterTag (a known limitation of the flattened Markdown source). Surfaced for honest coverage reporting; absent when the body came straight from the spec.

Reqdtypesince 0.1.0

Source: packages/fix/src/dictionary/types.ts:21

Required-ness of a member: Y required, N optional, C conditional (rule in prose).

BaseTypetypesince 0.1.0

Source: packages/fix/src/dictionary/types.ts:24

The five root FIX datatypes every other datatype derives from.

int
float
char
String
data

CoverageGapinterfacesince 0.1.0

interface CoverageGap

Source: packages/fix/src/dictionary/types.ts:166

A note about something the generated dictionary could not fully express, recorded for honest maturity reporting (per the open-source-readiness standard).

```
kind: string
```
Stable kind identifier, e.g. "nested-group-canonical", "unresolved-group".
```
where: string
```
Where the gap is, e.g. a message name + counter tag.
```
detail: string
```
What the dictionary cannot express and why.