Fields & Enumerations

Each type of Fieldset has at its core an array of fields - the definition of an individual field.

Fields may be either be a leaf field (with a wireId, name, datatype and description) or point to a component reference using componentKey.

json
{
    "name": "StandardHeader",
    "componentKey": "2PTE54fx",
    "key": "clOrdId",
    "alwaysRequired": true,
    "description": "<p>Standard Header.</p>"
},
{
    "name": "ClOrdID",
    "wireId": "11",
    "key": "6wH3gsLL",
    "datatype": "STRING",
    "alwaysRequired": true,
    "description": "<p>Client-assigned unique order identifier. Echoed on all subsequent messages.</p>"
}

Field Definition

💡 Difference to QuickFIX/FIX Orchestra

An important design difference between FinSpec and other FIX schemas relates to how fields are always explicitly defined within their fieldset context, and not referenced from a central location. We believe that this approach gives greater clarity and flexibility in defining field behaviour. For example:

  1. QuickFIX provides a single definition slot for fields, and references it throughout all messages and components. This means QuickFIX is unable to differentiate context (e.g. restricted enumerations) from one message to the next.

  2. FIX Orchestra also offers a central field definition, but with a complex set of overrides and annotations, which require extra logic to untangle.

  3. FIX Orchestra defines enumerations centrally as CodeSets, impacting the flexibility of defining context-specific enumerations within individual messages, components or views.

The primary disadvantage of FinSpec’s explicit field definition approach, is the potential for duplication it creates. Our experience, however, is that for most specifications this duplication is both manageable and easy to automate, and that the benefits of clarity and flexibility far outweigh the drawbacks.

Enumerations

A field may carry an enumerated set of valid values via the values array. Each entry maps a wire value to a human-readable name and/or a longer description — at least one of name or description must be present.

json
"values": [
  {
    "wireValue": "1",
    "name": "Market",
    "description": "Market order — execute at the best available price."
    },
  {
    "wireValue": "2",
    "name": "Limit",
    "description": "Limit order — execute at the specified price or better."
  },
  {
    "wireValue": "3",
    "name": "Stop",
    "description": "Stop order."
  },
  {
    "wireValue": "4",
    "name": "StopLimit",
    "description": "Stop limit order."
  }
]

A field may only carry enumerated values if its datatype has allowEnum: true. For example, CHAR and STRING types allow enumerations; PRICE and QTY do not — see Datatypes.

Repeating Groups

Repeating groups are expressed using nested fields. The parent field must have a datatype with isRepeatingStart: true (typically NUM_IN_GROUP in FIX). The fields array on that parent lists the member fields of the group.

json
{
    "name": "NoPartyIDs",
    "wireId": "453",
    "datatype": "NUM_IN_GROUP",
    "alwaysRequired": false,
    "description": "<p>Number of entries in the Parties repeating group.</p>",
    "fields": [
        {
            "name": "PartyID",
            "wireId": "448",
            "datatype": "STRING",
            "alwaysRequired": false,
            "description": "<p>Party identifier.</p>"
        },
        {
            "name": "PartyIDSource",
            "wireId": "447",
            "datatype": "CHAR",
            "alwaysRequired": false,
            "values": [
                { "wireValue": "B", "name": "BIC" },
                { "wireValue": "D", "name": "Proprietary" }
            ]
        },
        {
            "name": "PartyRole",
            "wireId": "452",
            "datatype": "INT",
            "alwaysRequired": false
        }
    ]
}

Repeating groups can be nested to arbitrary depth by placing further NUM_IN_GROUP-typed fields (with their own fields arrays) within the group’s member fields. This is used for constructs such as the Nested Parties block.

💡 Repeating Groups vs Components

The latest FIX standards have defined a very large number of repeating group structures, which look and feel very much like components. For API authors, it is always tempting to closely follow published patterns, but we recommend considering whether repeating groups really are re-used across your API.

  • If they are, then feel free to define them as reusable components and reference them within your fieldsets.
  • If they are not, then it is better to “inline” them as nested fields arrays to keep the context of where they are used.