---
seo:
    title: "FinSpec Metadata"
    description: "Information about metadata FinSpec sections, covering both issuer and document."
llm_context: "In-depth description of v5.2 `metadata` and `info` sections."
category: "reference"
related:
    - "/finspec"
---

## Spec Metadata

A FinSpec document contains three different metadata sections, all of which are mandatory.

- **`metadata`**: Contains information about the organisation that authored the specification.
- **`info`**: Provides information about the document itself.
- **`protocol`**: Describes the protocol used by the service.

### `metadata` Section

`metadata` describes the **organisation** that has authored the specification — the venue,
software vendor, or standards body. This information is expected to be very slow-moving and used across multiple documents.

```json
"metadata": {
  "issuer": "FIX Trading Community",
  "purpose": "Standard FIX 4.4 specification for equity order entry.",
  "logo": "https://example.com/logo.png",
  "contacts": [
    { "name": "API Support", "email": "api-support@example.com", "phone": "+44 20 7946 0000" }
  ],
  "links": [
    { "name": "Homepage", "url": "https://www.example.com" },
    { "name": "GitHub", "url": "https://github.com/example/fix-spec" }
  ]
}
```

```jsonSchema protocol=finspec version=5.2 def=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-": {
                        "description": "Any property starting with x- is valid.",
                        "additionalProperties": true,
                        "additionalItems": true,
                        "$refName": "vendorExtension",
                        "$refResolved": true
                    }
                },
                "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-": {
                        "description": "Any property starting with x- is valid.",
                        "additionalProperties": true,
                        "additionalItems": true,
                        "$refName": "vendorExtension",
                        "$refResolved": true
                    }
                },
                "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
        }
    }
}
```

The metadata section also carries contact information for the organisation, via two arrays: `contacts` and `links`.

```jsonSchema protocol=finspec version=5.2 def=contact
{
    "type": "object",
    "required": [
        "name"
    ],
    "description": "Contact details of representatives who can answer questions about this document.",
    "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 (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."
        }
    }
}
```

```jsonSchema protocol=finspec version=5.2 def=link
{
    "type": "object",
    "description": "A customer-facing URL link with additional, relevant information.",
    "required": [
        "name",
        "url"
    ],
    "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 display name of the link."
        },
        "url": {
            "type": "string",
            "format": "uri",
            "description": "The fully qualified URL of the link, including the protocol (e.g., https://)."
        }
    }
}
```

### `info` Section

In contrast to the `metadata` section, the `info` section describes **this document version**: its title, version number, lifecycle dates, and license.

```json
"info": {
  "title": "Trading Specification",
  "version": "10.2.1",
  "status": "ACTIVE",
  "issueDate": "2024-01-15",
  "liveDate": "2024-02-01",
  "description": "Description of our order-entry specification.",
  "license": "Closed"
}
```

```jsonSchema protocol=finspec version=5.2 def=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-": {
                        "description": "Any property starting with x- is valid.",
                        "additionalProperties": true,
                        "additionalItems": true,
                        "$refName": "vendorExtension",
                        "$refResolved": true
                    }
                },
                "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
        }
    }
}
```

FinSpec mandates a [Semantic Versioning](https://semver.org/) reference in the `version` attribute, in the form of either `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`. We **strongly support** this convention for all document versions, as it directly leads to better communication of API versions for customers.

The optional `license` attribute relates to the licensing of **the API document** itself, as opposed to the service or any software associated with it. Most trading firms will consider their documentation to be proprietary, and will therefore choose "Closed".

### `protocol` Section

This section identifies the wire protocol described by the specification.

:::info
Version 5.2 of the FinSpec schema has been restricted to the FIX protocol only. Future versions will expand to other, non-FIX protocols.
:::

```json
"protocol": {
  "name": "FIX",
  "version": "4.4"
}
```

```jsonSchema protocol=finspec version=5.2 def=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"
        ]
    }
}
```
