Data Types

Our APIs deal with many different types of data, this page serves to define some of the core, common datatypes and our standard formats for these.

Date and Datetime

All our date and datetime fields will be represented using standard ISO 8601 format.

• Date format - yyyy-MM-dd, e.g. 2021-06-22
• Datetime format - yyyy-MM-ddTHH:mm:ssZ, e.g. 2021-06-22T14:26:30+01:00

Note that Z may be used to represent the UTC time +00:00.

Currency

All currency values are represented as strings with a decimal, for example a value of £123.45 would be presented as "123.45".

In most cases these numbers will be shown in two decimal places, however there may be times when additional decimals are required for fractional currency values. Fields where this is possible will be clearly documented.

Polymorphic Objects

Some fields may allow for polymorphic objects, this is where a field can contain an object type that may be one of a few defined sub-objects each with their own structure. For example,

  pets: [
    {
      "type": "CAT",
      "name": "Luna",
      "meows": 324
    },
    {
      "type": "DOG",
      "name": "Pluto",
      "woofs": 129
    }
  ]

In this example, the pets field can contain objects of type Pet, the subtypes of Pet being Cat and Dog. This is indicated by the discriminator field type. All Pet objects have a name, but Dogs have a woofs count while Cats have meows. Other fields may be totally dependant on the underlying type.

In our APIs we use this technique sparingly to avoid over-complicating things, however we do use it where it serves to simplify data structures and avoid redundant fields.