---
seo:
    title: "Fields"
    description: "The definition of the fields and enumerations within FinSpec fieldsets."
llm_context: "Reference for FinSpec field and enumeration definitions."
category: "reference"
related:
    - "/finspec/reference"
    - "/finspec/reference/datatypes"
---

## Fields & Enumerations

Each type of [Fieldset](/finspec/reference/fieldsets#fieldsets) 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

:::tip 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.
:::

```jsonSchema protocol=finspec version=5.2 def=field
{
    "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": {
                "type": "object",
                "required": [
                    "wireValue"
                ],
                "description": "An individual allowed enumerated value for this field.",
                "anyOf": [
                    {
                        "required": [
                            "name"
                        ]
                    },
                    {
                        "required": [
                            "description"
                        ]
                    }
                ],
                "additionalProperties": false,
                "patternProperties": {
                    "^x-": {
                        "description": "Any property starting with x- is valid.",
                        "additionalProperties": true,
                        "additionalItems": true,
                        "$refName": "vendorExtension",
                        "$refResolved": true
                    }
                },
                "properties": {
                    "wireValue": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "number"
                            }
                        ],
                        "description": "The enumerated option, as it would appear on the wire."
                    },
                    "name": {
                        "description": "Short, human-readable name of the enumerated option. For FIX, this is used for QuickFIX XML.",
                        "type": "string"
                    },
                    "description": {
                        "description": "A human-readable description of the enumerated option.",
                        "type": "string"
                    }
                },
                "$refName": "enum",
                "$refResolved": true
            },
            "$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": {
                        "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": "The human-readable explanation of the condition under which this field is conditionally required.",
            "$refName": "conditionHuman",
            "$refResolved": true
        },
        "fields": {
            "type": "array",
            "description": "The nested set of child fields where this field represents the start of a repeating group.",
            "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
        },
        "example": {
            "description": "An example value for this field.",
            "type": "string"
        }
    }
}
```

### 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."
  }
]
```

```jsonSchema protocol=finspec version=5.2 def=enum
{
    "type": "object",
    "required": [
        "wireValue"
    ],
    "description": "An individual allowed enumerated value for this field.",
    "anyOf": [
        {
            "required": [
                "name"
            ]
        },
        {
            "required": [
                "description"
            ]
        }
    ],
    "additionalProperties": false,
    "patternProperties": {
        "^x-": {
            "description": "Any property starting with x- is valid.",
            "additionalProperties": true,
            "additionalItems": true,
            "$refName": "vendorExtension",
            "$refResolved": true
        }
    },
    "properties": {
        "wireValue": {
            "oneOf": [
                {
                    "type": "string"
                },
                {
                    "type": "number"
                }
            ],
            "description": "The enumerated option, as it would appear on the wire."
        },
        "name": {
            "description": "Short, human-readable name of the enumerated option. For FIX, this is used for QuickFIX XML.",
            "type": "string"
        },
        "description": {
            "description": "A human-readable description of the enumerated option.",
            "type": "string"
        }
    }
}
```

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](/finspec/reference/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.

:::tip 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.
:::
