---
seo:
    title: "FinSpec Datatypes"
    description: "The FinSpec datatypes object maps a fixed set of canonical type identifiers such as STRING, INT and PRICE onto base types."
llm_context: "Reference for the FinSpec datatypes key - the fixed set of UPPER_SNAKE_CASE type identifiers (FIX types plus REST types such as JSON and RFC3339_DATETIME) referenced from field.datatype."
category: "reference"
related:
    - "/finspec/reference"
    - "/finspec/reference/fieldsets"
---

## Datatypes

`datatypes` is an object defining the data types that can be referenced from `field.datatype`. Keys are canonical type identifiers in UPPER_SNAKE_CASE (e.g. `"STRING"`, `"INT"`, `"PRICE"`).

Since FinSpec 5.2 supports FIX only, the set of valid keys accepted by the `datatypes` object here is **fixed and closed** —
`additionalProperties` is `false`. As we introduce non-FIX protocols in future schema versions, this will change. This also means that - as of FinSpec 5.2 - the whole `datatypes` object is optional, as the FIX standard datatypes can be assumed.

```json
"datatypes": {
  "INT": {
    "name": "int",
    "baseType": "integer",
    "description": "<p>Sequence of digits without commas or decimals and optional sign character.</p>",
    "allowEnum": true,
    "examples": ["723 in field 21 would appear as '21=723'"]
  },
  "PRICE": {
    "name": "Price",
    "baseType": "number",
    "description": "<p>Float field representing a price. Note the number of decimal places may vary.</p>",
    "allowEnum": false,
    "isUnsigned": true
  },
  "NUM_IN_GROUP": {
    "name": "NumInGroup",
    "baseType": "integer",
    "description": "<p>Integer field representing the number of entries in a repeating group.</p>",
    "isRepeatingStart": true,
    "isUnsigned": true,
    "allowEnum": false
  }
}
```

:::info Why Not Just Use FIX Datatypes?
The answer lies in our goal of linking **across protocols**. While this would make perfect sense for a FIX API, as soon as you have a REST API alongside, then you are dealing with the set of datatypes that schema defines... and suddenly you find yourself writing boilerplate to simply translate mappings. Our uppercase names are designed to provide a higher abstraction layer, consistent across protocols.

Note also that FIX defines the placeholder datatypes of _Reserved100Plus_, _Reserved1000Plus_ and _Reserved4000Plus_. FinSpec does **not** support these datatypes, as they offer developers no practical assistance in understanding the actual shape of the fields. Please use meaningful datatypes instead.
:::

The full set of permitted keys, each expanded to its `datatypeEntry` shape:

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

### FIX Repeating Groups

Questions around the handling of FIX repeating groups are a common point of confusion here, and so it is worthwhile being precise about how to handle them.

In the JSON snippet above, there is a datatype of `NUM_IN_GROUP` that has `isRepeatingStart` set to `true`. This should be the datatype of the FIX field used to communicate the expected number of repetitions to follow (e.g. FIX tag 453 _NoPartyIDs_). The fields nested within this group should then be part of a child `fields` attribute.

See [Repeating Groups](/finspec/reference/fields#repeating-groups) for more information.

### FAQs

**Can I add a custom datatype that isn't in the fixed list?**
Not in FinSpec 5.2 — the `datatypes` object is closed to the standard FIX types while the schema only supports FIX. If you have a genuine gap, get in touch rather than working around it with a vendor extension, since datatypes affect validation and code generation across the whole spec.

**Do I need to declare `datatypes` at all if I'm only using standard FIX types?**
No. The whole `datatypes` object is optional in v5.2 — omit it and the standard FIX datatypes are assumed.
