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" }
  ]
}

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

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"
}

FinSpec mandates a Semantic Versioning 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"
}