---
seo:
    title: "FinSpec Reference"
    description: "Complete developer reference for the FinSpec v5.2 JSON format, including required top-level keys and document structure."
llm_context: "Entry point to the FinSpec v5.2 schema reference - describes the overall document shape and the required top-level keys (finspec, metadata, info and protocol)."
category: "reference"
related:
    - "/finspec"
    - "/finspec/reference/structure"
    - "/finspec/reference/datatypes"
    - "/finspec/reference/fieldsets"
    - "/finspec/reference/fields"
    - "/finspec/reference/conditions"
    - "/finspec/reference/metadata"
    - "/finspec/reference/changes"
---

## Overall Structure

This document describes the FinSpec v5.2 JSON format for authors writing or consuming FinSpec
specification files. It assumes familiarity with the FIX Protocol; the focus is on how to
express FIX specifications in the FinSpec schema rather than on FIX concepts themselves.

A FinSpec document is a single JSON object validated against a JSON Schema (draft-07). The
schema is strict: every object in the document sets `additionalProperties: false`, so a document
may only use the keys described in this reference (plus [vendor extensions](#vendor-extensions)).
Any property tooling encounters that isn't documented here is not part of the format.

The following top-level keys are **required**: `finspec`, `metadata`, `info`, `protocol`.
All other top-level keys are optional. A minimal valid document looks like:

```json
{
    "finspec": "5.2",
    "metadata": {
        "issuer": "Acme Exchange"
    },
    "info": {
        "title": "Acme FIX Specification",
        "version": "1.0.0"
    },
    "protocol": {
        "name": "FIX",
        "version": "4.4"
    }
}
```

The full shape of the top-level document — every key, its type, and whether it's required — is
below.

```jsonSchema protocol=finspec version=5.2
{
    "title": "A JSON Schema for FinSpec v5.2.",
    "id": "https://fixspec.com/finspec/v5.2/schema.json#",
    "description": "Public JSON Schema for FinSpec documents describing financial protocol specifications.",
    "type": "object",
    "required": [
        "finspec",
        "metadata",
        "info",
        "protocol"
    ],
    "additionalProperties": false,
    "patternProperties": {
        "^x-": {
            "description": "Any property starting with x- is valid.",
            "additionalProperties": true,
            "additionalItems": true,
            "$refName": "vendorExtension",
            "$refResolved": true
        }
    },
    "properties": {
        "finspec": {
            "type": "string",
            "enum": [
                "5.2"
            ],
            "description": "The FinSpec version of this document."
        },
        "metadata": {
            "type": "object",
            "description": "General metadata about the author of the API.",
            "required": [
                "issuer"
            ],
            "additionalProperties": false,
            "patternProperties": {
                "^x-": {
                    "description": "Any property starting with x- is valid.",
                    "additionalProperties": true,
                    "additionalItems": true,
                    "$refName": "vendorExtension",
                    "$refResolved": true
                }
            },
            "properties": {
                "issuer": {
                    "type": "string",
                    "description": "The name of the API issuer."
                },
                "purpose": {
                    "type": "string",
                    "description": "A description about the overall purpose of the document."
                },
                "logo": {
                    "type": "string",
                    "description": "A fully-qualified URL to a suitable logo image for the spec author."
                },
                "contacts": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true,
                    "description": "An array of customer-facing contacts for queries related to the document.",
                    "items": {
                        "type": "object",
                        "required": [
                            "name"
                        ],
                        "description": "Contact details of representatives who can answer questions about this document.",
                        "additionalProperties": false,
                        "patternProperties": {
                            "^x-": {
                                "$refName": "vendorExtension",
                                "$refResolved": false
                            }
                        },
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The name (or team name) of the contact."
                            },
                            "phone": {
                                "type": "string",
                                "description": "Phone number including international and local dialling codes."
                            },
                            "email": {
                                "type": "string",
                                "format": "email",
                                "description": "The email address of the contact."
                            }
                        },
                        "$refName": "contact",
                        "$refResolved": true
                    },
                    "$refName": "contacts",
                    "$refResolved": true
                },
                "links": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true,
                    "description": "An array of customer-facing URL links with additional, relevant information.",
                    "items": {
                        "type": "object",
                        "description": "A customer-facing URL link with additional, relevant information.",
                        "required": [
                            "name",
                            "url"
                        ],
                        "additionalProperties": false,
                        "patternProperties": {
                            "^x-": {
                                "$refName": "vendorExtension",
                                "$refResolved": false
                            }
                        },
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The display name of the link."
                            },
                            "url": {
                                "type": "string",
                                "format": "uri",
                                "description": "The fully qualified URL of the link, including the protocol (e.g., https://)."
                            }
                        },
                        "$refName": "link",
                        "$refResolved": true
                    },
                    "$refName": "links",
                    "$refResolved": true
                }
            },
            "$refName": "metadata",
            "$refResolved": true
        },
        "info": {
            "type": "object",
            "description": "Metadata about the document itself.",
            "required": [
                "version",
                "title"
            ],
            "additionalProperties": false,
            "patternProperties": {
                "^x-": {
                    "description": "Any property starting with x- is valid.",
                    "additionalProperties": true,
                    "additionalItems": true,
                    "$refName": "vendorExtension",
                    "$refResolved": true
                }
            },
            "properties": {
                "title": {
                    "type": "string",
                    "description": "The title of the document."
                },
                "version": {
                    "type": "string",
                    "description": "The schemantic version number of the API in the form `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`.",
                    "pattern": "^\\d+\\.\\d+(\\.\\d+)?$"
                },
                "links": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true,
                    "description": "An array of customer-facing URL links with additional, relevant information.",
                    "items": {
                        "type": "object",
                        "description": "A customer-facing URL link with additional, relevant information.",
                        "required": [
                            "name",
                            "url"
                        ],
                        "additionalProperties": false,
                        "patternProperties": {
                            "^x-": {
                                "$refName": "vendorExtension",
                                "$refResolved": false
                            }
                        },
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The display name of the link."
                            },
                            "url": {
                                "type": "string",
                                "format": "uri",
                                "description": "The fully qualified URL of the link, including the protocol (e.g., https://)."
                            }
                        },
                        "$refName": "link",
                        "$refResolved": true
                    },
                    "$refName": "links",
                    "$refResolved": true
                },
                "issueDate": {
                    "type": "string",
                    "format": "date",
                    "description": "The date that this version is issued or published.",
                    "pattern": "^(19|20)\\d{2}-(0\\d|1[012])-([0-2]\\d|3[01])$"
                },
                "liveDate": {
                    "type": "string",
                    "format": "date",
                    "description": "The target date that this version goes live into a production environment.",
                    "pattern": "^(19|20)\\d{2}-(0\\d|1[012])-([0-2]\\d|3[01])$"
                },
                "deprecatedDate": {
                    "type": "string",
                    "format": "date",
                    "description": "The date on which this version was considered deprecated.",
                    "pattern": "^(19|20)\\d{2}-(0\\d|1[012])-([0-2]\\d|3[01])$"
                },
                "description": {
                    "type": "string",
                    "description": "A brief description of the document."
                },
                "status": {
                    "type": "string",
                    "description": "The current status of the document.",
                    "enum": [
                        "DRAFT",
                        "ACTIVE",
                        "FINAL"
                    ]
                },
                "license": {
                    "type": "string",
                    "description": "The license under which the document is made available.",
                    "enum": [
                        "Closed",
                        "Apache 2.0",
                        "GNU",
                        "BSD"
                    ],
                    "$refName": "license",
                    "$refResolved": true
                }
            },
            "$refName": "info",
            "$refResolved": true
        },
        "tags": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "description": "A list of light-weight tags associated with the document as a whole.",
            "items": {
                "type": "object",
                "required": [
                    "tag"
                ],
                "additionalProperties": false,
                "description": "A light-weight string tag, providing additional context and organisation.",
                "patternProperties": {
                    "^x-": {
                        "description": "Any property starting with x- is valid.",
                        "additionalProperties": true,
                        "additionalItems": true,
                        "$refName": "vendorExtension",
                        "$refResolved": true
                    }
                },
                "properties": {
                    "tag": {
                        "type": "string",
                        "description": "The light-weight string tag itself."
                    },
                    "description": {
                        "type": "string",
                        "description": "A brief description of the tag providing additional context."
                    }
                },
                "$refName": "tag",
                "$refResolved": true
            },
            "$refName": "tags",
            "$refResolved": true
        },
        "protocol": {
            "type": "object",
            "description": "The protocol used in the document.",
            "required": [
                "name"
            ],
            "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 protocol.",
                    "enum": [
                        "FIX"
                    ]
                },
                "version": {
                    "type": "string",
                    "description": "The version of the protocol.",
                    "enum": [
                        "4.0",
                        "4.1",
                        "4.2",
                        "4.3",
                        "4.4",
                        "Latest"
                    ]
                }
            },
            "if": {
                "properties": {
                    "name": {
                        "const": "FIX"
                    }
                },
                "required": [
                    "name"
                ]
            },
            "then": {
                "required": [
                    "version"
                ]
            },
            "$refName": "protocol",
            "$refResolved": true
        },
        "changes": {
            "type": "object",
            "description": "An array of historical changes made to the document.",
            "required": [
                "lastVersion",
                "history"
            ],
            "additionalProperties": false,
            "patternProperties": {
                "^x-": {
                    "description": "Any property starting with x- is valid.",
                    "additionalProperties": true,
                    "additionalItems": true,
                    "$refName": "vendorExtension",
                    "$refResolved": true
                }
            },
            "properties": {
                "lastVersion": {
                    "type": "string",
                    "description": "The current (latest) version of the document."
                },
                "history": {
                    "type": "array",
                    "description": "Historical changes made to the document.",
                    "items": {
                        "type": "object",
                        "required": [
                            "version",
                            "issueDate",
                            "summary"
                        ],
                        "description": "A single historical change entry.",
                        "additionalProperties": false,
                        "patternProperties": {
                            "^x-": {
                                "description": "Any property starting with x- is valid.",
                                "additionalProperties": true,
                                "additionalItems": true,
                                "$refName": "vendorExtension",
                                "$refResolved": true
                            }
                        },
                        "properties": {
                            "version": {
                                "type": "string",
                                "description": "The version number of the change. Typically follows semantic versioning, but may be non-standard for legacy documents."
                            },
                            "issueDate": {
                                "type": "string",
                                "format": "date",
                                "description": "The date when the version was issued.",
                                "pattern": "^(19|20)\\d{2}-(0\\d|1[012])-([0-2]\\d|3[01])$"
                            },
                            "summary": {
                                "description": "A brief summary of the change.",
                                "type": "string"
                            },
                            "liveDate": {
                                "type": "string",
                                "format": "date",
                                "description": "The date when the version entered into production.",
                                "pattern": "^(19|20)\\d{2}-(0\\d|1[012])-([0-2]\\d|3[01])$"
                            },
                            "deprecatedDate": {
                                "type": "string",
                                "format": "date",
                                "description": "The date when the version was deprecated.",
                                "pattern": "^(19|20)\\d{2}-(0\\d|1[012])-([0-2]\\d|3[01])$"
                            },
                            "description": {
                                "description": "A detailed description of the change.",
                                "type": "string"
                            }
                        },
                        "$refName": "change",
                        "$refResolved": true
                    },
                    "uniqueItems": true
                }
            },
            "$refName": "changes",
            "$refResolved": true
        },
        "datatypes": {
            "type": "object",
            "description": "The universe of datatypes for the protocol. We adopt consistent, protocol-agnostic, UPPER_SNAKE_CASE identifiers (e.g. PRICE, UTC_TIMESTAMP) to allow cross-protocol mapping.",
            "additionalProperties": false,
            "patternProperties": {
                "^(INT|UINT|LENGTH|TAG_NUM|SEQ_NUM|NUM_IN_GROUP|DAY_OF_MONTH|FLOAT|QTY|PRICE|PRICE_OFFSET|AMT|PERCENTAGE|CHAR|BOOLEAN|STRING|MULTI_CHAR_VALUE|MULTI_STRING_VALUE|COUNTRY|CURRENCY|EXCHANGE|MONTH_YEAR|UTC_TIMESTAMP|UTC_TIME|UTC_DATE|LOCAL_DATE|TIMEZONE_TIME|TIMEZONE_TIMESTAMP|RAW_DATA|PATTERN|TENOR|RESERVED_100_PLUS|RESERVED_1000_PLUS|RESERVED_4000_PLUS|XML|LANGUAGE|LOCAL_TIME|XID|XIDREF|)$": {
                    "type": "object",
                    "description": "A single datatype definition.",
                    "required": [
                        "name",
                        "baseType",
                        "description"
                    ],
                    "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 datatype. For FIX, this will be the commonly-known FIX datatype identifier (eg LocalMktDate)."
                        },
                        "examples": {
                            "type": "array",
                            "description": "Array of example values for this datatype.",
                            "items": {
                                "type": "string"
                            }
                        },
                        "allowEnum": {
                            "description": "Whether this datatype may allow enumerated values.",
                            "type": "boolean"
                        },
                        "isRepeatingStart": {
                            "description": "Whether this datatype is the start of a repeating group.",
                            "type": "boolean"
                        },
                        "baseType": {
                            "type": "string",
                            "description": "The canonical, protocol-agnostic primitive this datatype resolves to.",
                            "enum": [
                                "int",
                                "decimal",
                                "char",
                                "boolean",
                                "string",
                                "data",
                                "date",
                                "time",
                                "timestamp",
                                "time_tz",
                                "timestamp_tz"
                            ]
                        },
                        "description": {
                            "description": "A human-readable description of the datatype.",
                            "type": "string"
                        },
                        "length": {
                            "type": "integer",
                            "minimum": 1,
                            "description": "Fixed wire-format width: bytes for binary protocol fields, or characters for a fixed-width text/padded field."
                        },
                        "precision": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "Number of fractional digits implied by the wire encoding. For a 'decimal' baseType, the number of implied decimal places when the value is transmitted as a scaled integer (e.g. an ITCH price field with 4 implied decimals). For a 'time'/'timestamp'/'time_tz'/'timestamp_tz' baseType, the number of sub-second digits the wire format carries (e.g. 9 for nanosecond-precision exchange timestamps)."
                        },
                        "isUnsigned": {
                            "description": "Whether this datatype represents an unsigned value.",
                            "type": "boolean"
                        },
                        "pattern": {
                            "type": "string",
                            "description": "A regular expression pattern that the value of this datatype must match."
                        },
                        "padChar": {
                            "type": "string",
                            "description": "The character used for padding if the field has a fixed width."
                        },
                        "padSide": {
                            "type": "string",
                            "description": "The side of the field where padding is applied.",
                            "enum": [
                                "left",
                                "right"
                            ]
                        }
                    },
                    "$refName": "datatypeEntry",
                    "$refResolved": true
                }
            },
            "$refName": "datatypes",
            "$refResolved": true
        },
        "components": {
            "type": "object",
            "description": "A collection of reusable components, keyed by a unique string reference. We recommend AGAINST using names as the keys, as this leads to brittle references and false coding assumptions.",
            "additionalProperties": {
                "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": {
                            "$refName": "field",
                            "$refResolved": false
                        },
                        "$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"
                        ]
                    }
                },
                "$refName": "fieldSet",
                "$refResolved": true
            },
            "$refName": "components",
            "$refResolved": true
        },
        "messages": {
            "type": "object",
            "description": "A collection of technical message payloads, keyed by a unique string reference. We recommend AGAINST using names as the keys, as this leads to brittle references and false coding assumptions.",
            "additionalProperties": {
                "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": {
                            "$refName": "field",
                            "$refResolved": false
                        },
                        "$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"
                        ]
                    }
                },
                "$refName": "fieldSet",
                "$refResolved": true
            },
            "$refName": "messages",
            "$refResolved": true
        },
        "views": {
            "type": "object",
            "description": "A collection of context-specific message payloads, keyed by a unique string reference. We recommend AGAINST using names as the keys, as this leads to brittle references and false coding assumptions.",
            "additionalProperties": {
                "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": {
                                    "$refName": "conditionAndGroup",
                                    "$refResolved": false
                                },
                                "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": {
                            "$refName": "field",
                            "$refResolved": false
                        },
                        "$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"
                        ]
                    }
                },
                "$refName": "fieldSetWithContext",
                "$refResolved": true
            },
            "$refName": "views",
            "$refResolved": true
        }
    }
}
```

### Vendor Extensions

Any property at any level whose key begins with `x-` is a **vendor extension**. Extensions are
permitted wherever you see the green "vendor extensions" marker (see below), and may contain arbitrary data.

![Figure: Vendor extension marker](https://docs.fixspec.com/api/docs/image/vendor_extensions.png)

Vendor extensions should be ignored by any application that isn't configured to use them.

```json
"metadata": {
  "issuer": "Acme Exchange",
  "x-internal-id": "AE-FIX44-PROD",
  "x-owner-team": "connectivity-engineering"
}
```
