Fieldsets
The term “Fieldsets” refers to any structured collection of fields that together define the payload that can be exchanged in the API. FinSpec supports three types of fieldsets.
- Components: Re-usable groups of fields that can be shared across multiple messages.
- Technical Messages: Standard message definitions exchanged in the API.
- Functional Views: Context-specific projections of technical messages, describing how a message is used in a particular scenario or context.
Re-usable Components
components is an object containing reusable field groups — the building blocks shared across
multiple messages. Typical examples include the standard FIX header, the standard trailer, and
common repeating groups such as the Parties block.
In a FinSpec document, these are defined centrally in the components object, comply with the fieldSet schema and allocated a unique identifying key.
json"components": {
"NCnKSZCA": {
"name": "StandardHeader",
"description": "<p>The standard FIX message header, present on all messages.</p>",
"isHeader": true,
"key": "NCnKSZCA",
"fields": [
{
"name": "BeginString",
"wireId": "8",
"datatype": "STRING",
"alwaysRequired": true
},
{
"name": "BodyLength",
"wireId": "9",
"datatype": "LENGTH",
"alwaysRequired": true
},
{
"name": "MsgType",
"wireId": "35",
"datatype": "STRING",
"alwaysRequired": true
}
...
]
}
}
Once defined, a component is then referenced from a field within a message by using componentKey. Such fields do not have a datatype specified.
json "fields": [
{
"name": "StandardHeader",
"componentKey": "NCnKSZCA"
}
...
]
Two of the most common components are header and footers. The attributes isHeader and isTrailer are used to indicate which components serve in this role, offering more reliable identification than name alone.
Technical Messages
Technical messages are what you most commonly see in “traditional” API specifications - a description of a message payload as it appears on the wire. There is no context to it; it simply lists the full set of possible contents.
As with components, technical messages should comply with the fieldSet schema and are allocated a unique identifying key.
json"messages": {
"qZlC34H4": {
"name": "NewOrderSingle",
"wireId": "D",
"key": "qZlC34H4",
"description": "<p>Used to submit a new order to the market.</p>",
"isSession": false,
"direction": "in",
"fields": [
{
"name": "StandardHeader",
"componentKey": "NCnKSZCA"
},
{
"name": "ClOrdID",
"wireId": "11",
"datatype": "STRING",
"alwaysRequired": true,
"description": "<p>Unique client-assigned order identifier.</p>"
},
{
"name": "OrdType",
"wireId": "40",
"datatype": "CHAR",
"alwaysRequired": true,
"values": [
{
"wireValue": "1",
"name": "Market",
"description": "Market order."
},
{
"wireValue": "2",
"name": "Limit",
"description": "Limit order."
}
]
}
...
]
}
}
The isSession flag distinguishes session-layer messages (Logon, Heartbeat, Logout, etc.) from application messages. This flag is designed to help code generation limit their scope to application-level messages only, as session-layer is typically taken care of by the FIX engine itself.
Functional Views
The final type of fieldset supported is a functional view: a refinement of another reference fieldset (technical message or functional view) within a specific business context. Real-world examples might include a series of “views” of the generic NewOrderSingle technical message description tailored by algo order type, or differentiating a fill ExecutionReport from a simple ExecutionReport acknowledgement.
The key concept is that a view represents a context-specific perspective on a more generic underlying message. It is this context-specific refinement that differentiates a view from the base message itself, and is the reason why these views must comply with the fieldsetWithContext schema.
Each view carries a mandatory wireId and condition that identifies the context. Within that context, the view’s fields
array may:
- Restrict the set of fields to only those relevant in this context, replacing “if… then…” logic with an explicit list.
- Change field descriptions to reflect context-specific detail, leaving crisp definitions instead of long, generic prose.
- Tighten enumerations to include only the values relevant in this context.
- Alter requiredness to be more black-and-white about whether something is required in this context.
json"views": {
"llC3S4F1": {
"name": "New Order - Limit",
"wireId": "D",
"baseKey": "qZlC34H4",
"key": "llC3S4F1",
"description": "<p>NewOrderSingle submitted as a limit order.</p>",
"condition": {
"or": [
{
"and": [
{
"tag": "40",
"operator": "equals",
"value": "2",
"text": "OrdType equals 2 (Limit)"
}
]
}
]
},
"conditionHuman": "<p>OrdType (40) = 2 (Limit)</p>",
"direction": "in",
"fields": [
...
{
"name": "OrdType",
"wireId": "40",
"datatype": "CHAR",
"alwaysRequired": true,
"values": [
{
"wireValue": "2",
"name": "Limit"
}
]
},
{
"name": "Price",
"wireId": "44",
"datatype": "PRICE",
"alwaysRequired": true,
"description": "<p>Required for limit orders.</p>"
}
]
}
}
JSON Schema
fieldSet Schema
fieldSet is the common structure shared by both messages and components entries. It has a
name, description, and an ordered fields array, all required.
fieldSetWithContext Schema
fieldSetWithContext is the structure of an entry in views.
Implementation Notes
Use of Keys
As you learn more about FinSpec, it will become clear that key attributes are important linking values. There are some important constraints that FinSpec imposes on key values:
- They are alphanumeric strings of any length.
- They are case-sensitive.
- They should be unique (per type).
In FIX, it is tempting to use elements of the fieldset themselves as these keys - tag 35 (MsgType) for technical messages, and name for components. While this approach meets these criteria, we strongly discourage it, as it can lead to brittle linkages and potential duplicate entries. At FixSpec we use 8-character random strings for keys, drawn from a 62-character alphabet (a-z, A-Z, 0-9), offering around 218 trillion possible combinations.
Tracking Change Across Spec Versions
IMPORTANT: Consuming applications should not assume that the key value of a given fieldset (or field) remains constant across different versions of the specification. This is not a safe assumption, as it may be sourced from an underlying data store which uses the key in some other way.
For this reason, FinSpec supports an explicit historyKey attribute which is specifically designed to remain constant across versions, thus allowing developers an easy way to create spec differencing logic.
Direction Convention
Throughout the schema, direction values of "in" and "out" are expressed from the
perspective of the platform or server — i.e. the venue, exchange, or system described
by the specification.
| Value | Meaning |
|---|---|
"in" |
The message is received by the platform (i.e. sent by the client/buy-side). |
"out" |
The message is sent by the platform (i.e. received by the client/buy-side). |
"both" |
The message may flow in either direction. This is fieldSet.direction’s default. |
For example, a NewOrderSingle has direction: "in" because it is sent by a buy-side client and
received by the venue. An ExecutionReport has direction: "out" because the venue sends it to
the client. This convention applies to both fieldSet.direction and fieldSetWithContext.direction.
FAQs
What’s the difference between a component and a message?
A component is a reusable group of fields with no independent meaning of its own — it only exists once embedded inside a message via componentKey. A message is a complete, standalone payload that can actually be sent on the wire, identified by its own wireId.
Do I need to define a view for every message? No — views are optional. Define one only when a message behaves differently enough in a specific business context that it’s worth describing separately (different required fields, tighter enumerations, and so on). If a message means the same thing everywhere it’s used, there’s no need to add a view.
Why use random key values instead of something meaningful like the message name?
Names and wire IDs can be reused or renamed across spec versions, which makes them unreliable as permanent identifiers. A random key stays stable for the life of the fieldset, so tooling that links to it doesn’t break when the spec is edited.