---
seo:
    title: "Fieldsets"
    description: "The FinSpec components, messages and views objects hold the field-level definitions of a specification, from reusable field groups to conditional views."
llm_context: "Reference for FinSpec fieldSet and fieldSetWithContext objects - components, messages and views, the field-level definitions shared across a specification, including conditions and enumerations."
category: "reference"
related:
    - "/finspec/reference"
    - "/finspec/reference/datatypes"
    - "/finspec/reference/structure"
---

## 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.

1. **Components**: Re-usable groups of fields that can be shared across multiple messages.
2. **Technical Messages**: Standard message definitions exchanged in the API.
3. **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](/finspec/reference/fieldsets#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](/finspec/reference/fieldsets#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](/finspec/reference/fieldsets#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.

```jsonSchema protocol=finspec version=5.2 def=fieldSet
{
    "type": "object",
    "description": "A JSON object representing a set of fields (message or component).",
    "required": [
        "name",
        "description",
        "fields"
    ],
    "additionalProperties": false,
    "patternProperties": {
        "^x-": {
            "description": "Any property starting with x- is valid.",
            "additionalProperties": true,
            "additionalItems": true,
            "$refName": "vendorExtension",
            "$refResolved": true
        }
    },
    "properties": {
        "name": {
            "type": "string",
            "description": "The name of the field set."
        },
        "wireId": {
            "type": "string",
            "description": "The unique identifier for the fieldset in the wire format. For FIX protocol, this is Tag 35 _MsgType_."
        },
        "description": {
            "type": "string",
            "description": "A human-readable description of the field set."
        },
        "key": {
            "type": "string",
            "description": "The key used to reference this field set. Should be the same as the object key."
        },
        "historyKey": {
            "type": "string",
            "description": "The consistent, historic key used to cross-reference this fieldset in previous versions of this document."
        },
        "isSession": {
            "description": "Indicates whether this field set is part of the session-level messages.",
            "type": "boolean"
        },
        "isHeader": {
            "description": "Indicates whether this is a standard header component.",
            "type": "boolean"
        },
        "isTrailer": {
            "description": "Indicates whether this is a standard trailer component.",
            "type": "boolean"
        },
        "fields": {
            "type": "array",
            "description": "An array of fields.",
            "minItems": 1,
            "items": {
                "type": "object",
                "description": "A field within a field set.",
                "required": [
                    "name"
                ],
                "anyOf": [
                    {
                        "required": [
                            "componentKey"
                        ]
                    },
                    {
                        "required": [
                            "datatype"
                        ]
                    }
                ],
                "additionalProperties": false,
                "patternProperties": {
                    "^x-": {
                        "description": "Any property starting with x- is valid.",
                        "additionalProperties": true,
                        "additionalItems": true,
                        "$refName": "vendorExtension",
                        "$refResolved": true
                    }
                },
                "properties": {
                    "wireId": {
                        "type": "string",
                        "description": "The wire ID associated with this field, for example the FIX Tag number."
                    },
                    "key": {
                        "type": "string",
                        "description": "The unique key identifying this field within the field set."
                    },
                    "componentKey": {
                        "type": "string",
                        "description": "If the field points to a re-used component, then this is the key of the referenced component."
                    },
                    "description": {
                        "description": "A human-readable description of the field.",
                        "type": "string"
                    },
                    "name": {
                        "type": "string",
                        "description": "The human-readable name of the field."
                    },
                    "datatype": {
                        "type": "string",
                        "pattern": "^[A-Z][A-Z0-9_]*$",
                        "description": "The key of a datatype from this document's universe of datatypes."
                    },
                    "minValue": {
                        "description": "The minimum value allowed for this field (inclusive) for numeric fields.",
                        "type": "number"
                    },
                    "maxValue": {
                        "description": "The maximum value allowed for this field (inclusive) for numeric fields.",
                        "type": "number"
                    },
                    "minLength": {
                        "description": "The minimum length allowed for this field (inclusive) for string fields.",
                        "type": "integer",
                        "minimum": 0
                    },
                    "maxLength": {
                        "description": "The maximum length allowed for this field (inclusive) for string fields.",
                        "type": "integer",
                        "minimum": 0
                    },
                    "length": {
                        "description": "The exact length required for this field for string fields.",
                        "type": "integer",
                        "minimum": 0
                    },
                    "values": {
                        "type": "array",
                        "minItems": 1,
                        "description": "The set of allowed enumerated values for this field.",
                        "uniqueItems": true,
                        "items": {
                            "$refName": "enum",
                            "$refResolved": false
                        },
                        "$refName": "enumArray",
                        "$refResolved": true
                    },
                    "alwaysRequired": {
                        "description": "Indicates whether this field is always required.",
                        "type": "boolean"
                    },
                    "condition": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "description": "The machine-readable condition under which this field is conditionally required.",
                        "additionalProperties": false,
                        "properties": {
                            "or": {
                                "description": "A list of logical OR condition groups, at least ONE of which must evaluate to true in order for the overall condition to be true.",
                                "type": "array",
                                "items": {
                                    "$refName": "conditionAndGroup",
                                    "$refResolved": false
                                },
                                "minItems": 1
                            }
                        },
                        "$refName": "condition",
                        "$refResolved": true
                    },
                    "conditionHuman": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The human-readable explanation of the condition under which this field is conditionally required.",
                        "$refName": "conditionHuman",
                        "$refResolved": true
                    },
                    "fields": {
                        "description": "The nested set of child fields where this field represents the start of a repeating group.",
                        "$refName": "fieldArray",
                        "$refResolved": false
                    },
                    "example": {
                        "description": "An example value for this field.",
                        "type": "string"
                    }
                },
                "$refName": "field",
                "$refResolved": true
            },
            "$refName": "fieldArray",
            "$refResolved": true
        },
        "direction": {
            "description": "The direction that the fieldset can travel from the perspective of the API provider.",
            "type": "string",
            "enum": [
                "in",
                "out",
                "both"
            ]
        }
    }
}
```

#### `fieldSetWithContext` Schema

`fieldSetWithContext` is the structure of an entry in `views`.

```jsonSchema protocol=finspec version=5.2 def=fieldSetWithContext
{
    "type": "object",
    "description": "A functional view representing a field set (message) within a specific business context, narrowed by condition and/or direction.",
    "required": [
        "name",
        "wireId",
        "description",
        "fields",
        "condition"
    ],
    "additionalProperties": false,
    "patternProperties": {
        "^x-": {
            "description": "Any property starting with x- is valid.",
            "additionalProperties": true,
            "additionalItems": true,
            "$refName": "vendorExtension",
            "$refResolved": true
        }
    },
    "properties": {
        "name": {
            "type": "string",
            "description": "The name of the field set (view)."
        },
        "wireId": {
            "type": "string",
            "description": "The wire identifier of the field set (view)."
        },
        "description": {
            "type": "string",
            "description": "A human-readable description of the field set (view)."
        },
        "isSession": {
            "description": "Indicates whether this field set is part of the session-level messages.",
            "type": "boolean"
        },
        "condition": {
            "type": [
                "object",
                "null"
            ],
            "description": "The machine-readable condition under which this field set (view) is applicable.",
            "additionalProperties": false,
            "properties": {
                "or": {
                    "description": "A list of logical OR condition groups, at least ONE of which must evaluate to true in order for the overall condition to be true.",
                    "type": "array",
                    "items": {
                        "type": "object",
                        "description": "A sub-condition of the condition descrption.",
                        "required": [
                            "and"
                        ],
                        "additionalProperties": false,
                        "properties": {
                            "and": {
                                "description": "A list of logical AND conditions, ALL of which must evaluate to true in order for the sub-condition to be true.",
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "required": [
                                        "tag",
                                        "operator"
                                    ],
                                    "description": "A single condition node within a logical AND group.",
                                    "additionalProperties": false,
                                    "properties": {
                                        "tag": {
                                            "description": "The field to which this condition applies.",
                                            "type": [
                                                "string",
                                                "integer"
                                            ]
                                        },
                                        "operator": {
                                            "type": "string",
                                            "enum": [
                                                "present",
                                                "not_present",
                                                "equals",
                                                "not_equals",
                                                "one_of",
                                                "not_in",
                                                "equals_field",
                                                "not_equals_field",
                                                "starts_with",
                                                "ends_with",
                                                "contains",
                                                "regex",
                                                "not_regex",
                                                "gt",
                                                "gte",
                                                "lt",
                                                "lte",
                                                "gt_field",
                                                "gte_field",
                                                "lt_field",
                                                "lte_field"
                                            ],
                                            "description": "The operator to apply to the field specified in the tag."
                                        },
                                        "reference": {
                                            "description": "A reference field value to be used for dynamic comparison (if applicable).",
                                            "type": [
                                                "string",
                                                "null"
                                            ]
                                        },
                                        "value": {
                                            "description": "A fixed value to compare the field against (if applicable).",
                                            "type": [
                                                "string",
                                                "null"
                                            ]
                                        },
                                        "text": {
                                            "type": "string",
                                            "description": "A human-readable description of this condition node."
                                        },
                                        "or_missing": {
                                            "type": "boolean",
                                            "description": "Indicates whether this condition should be considered true if the field is missing."
                                        }
                                    },
                                    "$refName": "conditionNode",
                                    "$refResolved": true
                                },
                                "minItems": 1
                            }
                        },
                        "$refName": "conditionAndGroup",
                        "$refResolved": true
                    },
                    "minItems": 1
                }
            },
            "$refName": "condition",
            "$refResolved": true
        },
        "conditionHuman": {
            "type": [
                "string",
                "null"
            ],
            "description": "A human-readable description of the condition (view) under which this field set (view) is applicable.",
            "$refName": "conditionHuman",
            "$refResolved": true
        },
        "fields": {
            "type": "array",
            "description": "The array of fields contained within this field set (view).",
            "minItems": 1,
            "items": {
                "type": "object",
                "description": "A field within a field set.",
                "required": [
                    "name"
                ],
                "anyOf": [
                    {
                        "required": [
                            "componentKey"
                        ]
                    },
                    {
                        "required": [
                            "datatype"
                        ]
                    }
                ],
                "additionalProperties": false,
                "patternProperties": {
                    "^x-": {
                        "description": "Any property starting with x- is valid.",
                        "additionalProperties": true,
                        "additionalItems": true,
                        "$refName": "vendorExtension",
                        "$refResolved": true
                    }
                },
                "properties": {
                    "wireId": {
                        "type": "string",
                        "description": "The wire ID associated with this field, for example the FIX Tag number."
                    },
                    "key": {
                        "type": "string",
                        "description": "The unique key identifying this field within the field set."
                    },
                    "componentKey": {
                        "type": "string",
                        "description": "If the field points to a re-used component, then this is the key of the referenced component."
                    },
                    "description": {
                        "description": "A human-readable description of the field.",
                        "type": "string"
                    },
                    "name": {
                        "type": "string",
                        "description": "The human-readable name of the field."
                    },
                    "datatype": {
                        "type": "string",
                        "pattern": "^[A-Z][A-Z0-9_]*$",
                        "description": "The key of a datatype from this document's universe of datatypes."
                    },
                    "minValue": {
                        "description": "The minimum value allowed for this field (inclusive) for numeric fields.",
                        "type": "number"
                    },
                    "maxValue": {
                        "description": "The maximum value allowed for this field (inclusive) for numeric fields.",
                        "type": "number"
                    },
                    "minLength": {
                        "description": "The minimum length allowed for this field (inclusive) for string fields.",
                        "type": "integer",
                        "minimum": 0
                    },
                    "maxLength": {
                        "description": "The maximum length allowed for this field (inclusive) for string fields.",
                        "type": "integer",
                        "minimum": 0
                    },
                    "length": {
                        "description": "The exact length required for this field for string fields.",
                        "type": "integer",
                        "minimum": 0
                    },
                    "values": {
                        "type": "array",
                        "minItems": 1,
                        "description": "The set of allowed enumerated values for this field.",
                        "uniqueItems": true,
                        "items": {
                            "$refName": "enum",
                            "$refResolved": false
                        },
                        "$refName": "enumArray",
                        "$refResolved": true
                    },
                    "alwaysRequired": {
                        "description": "Indicates whether this field is always required.",
                        "type": "boolean"
                    },
                    "condition": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "description": "The machine-readable condition under which this field is conditionally required.",
                        "additionalProperties": false,
                        "properties": {
                            "or": {
                                "description": "A list of logical OR condition groups, at least ONE of which must evaluate to true in order for the overall condition to be true.",
                                "type": "array",
                                "items": {
                                    "$refName": "conditionAndGroup",
                                    "$refResolved": false
                                },
                                "minItems": 1
                            }
                        },
                        "$refName": "condition",
                        "$refResolved": true
                    },
                    "conditionHuman": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The human-readable explanation of the condition under which this field is conditionally required.",
                        "$refName": "conditionHuman",
                        "$refResolved": true
                    },
                    "fields": {
                        "description": "The nested set of child fields where this field represents the start of a repeating group.",
                        "$refName": "fieldArray",
                        "$refResolved": false
                    },
                    "example": {
                        "description": "An example value for this field.",
                        "type": "string"
                    }
                },
                "$refName": "field",
                "$refResolved": true
            },
            "$refName": "fieldArray",
            "$refResolved": true
        },
        "key": {
            "type": "string",
            "description": "The unique key identifying this field set (view)."
        },
        "baseKey": {
            "type": "string",
            "description": "The base key from which this field set (view) is derived. For example, this is the key of the corresponding base message."
        },
        "historyKey": {
            "type": "string",
            "description": "The history key associated with this field set (view)."
        },
        "direction": {
            "description": "The direction in which this field set (view) is applicable.",
            "type": "string",
            "enum": [
                "in",
                "out",
                "both"
            ]
        }
    }
}
```

### 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:

1. They are alphanumeric strings of any length.
2. They are case-sensitive.
3. 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.
