Sharespine Developer Portal

Data types

Introduction

There are a number of basic data types to know about when working with the Integration Platform and these are outlined individually in this chapter, with examples.

But first there are some important things to know about fields in general. When reading and writing data to the Integration Platform one must know how fields (and their values) are interpreted in order to understand the consequence of the i/o operation conducted.

Field input (write)

Field is not included in the request body at all

No change, the field will remain its current value as is.

{
  "name": "My test product" // changes the name field, and leaves all other fields on record untouched.
}

Field is included in the request body and value is set to null

The current field will be cleared.

{
  "name": null // will clear the name field
}

Field is included in the request body and set to a value (including empty string)

The field will be set to the given value as long as the field and data type validation rules are met.

{
  "name": "My test product" // will set name of record to “My test product”
}

{
  "name": "" // will set the name field explicitly to an empty string
}

Field output (read)

Field with no value at all (null), then it will not show at all in responses alternatively show with value set to null.

Fields with empty strings are only shown if the field is of type string and the field has value explicitly set to an empty string.

String

Strings are straight forward. Nothing special, just plain strings.

String example

The sku field on a Product record.

Like so:

{
  "sku": "ABC123"
}

Number (Integer and Decimal)

Number values (like amounts, prices and such) must be encoded as an JSON string, not as a float/double value. This is to avoid rounding and precision issues that can arise using floats

Integer example

The weight field on a Product record.

Like so:

{
  "weight": "42"
}

and not like so:

{
  "weight": 42
}

Decimal example

The weight field on a Product record.

Like so:

{
  "weight": "42.2"
}

and not like so:

{
  "weight": 42.2
}

See these for more details:

Date time

All Date & time values are formatted according to RFC 3339. The server will always send the date/time using the UTC time zone with the Z suffix. The client should send the date/time in UTC with a Z suffix, however the client may use any format from RFC 3339.

Date time examples

Server sent orderTime field on an Order record. As stated before, the server will always send date times in UTC timezone.

{
  "orderTime": "2017-12-01T11:18:20Z",
  ...
}

Client sent value in UTC. No conversion needed by the server, value stored as is.

Request:

{
  "orderTime": "2017-12-01T11:18:20Z"
}

Response:

{
  "orderTime": "2017-12-01T11:18:20Z",
  ...
}

Client sent value in specific time zone using numeric offset. Conversion conducted by server into UTC time zone.

Request:

{
  "orderTime": "2017-12-01T11:18:20+01"
}

Response:

{
  "orderTime": "2017-12-01T10:18:20Z"
  ...
}

Client sent value in specific time zone using zone id offset. Conversion automatically conducted by server into UTC time zone.

Request:

{
  "orderTime": "2017-12-01T10:18:20Z+Europe/Stockholm"
}

Response:

{
  "orderTime": "2017-12-01T10:18:20Z"
  ...
}

Country (country code)

Country codes are defined in the ISO-3166-1 alpha-2 standard. The server will always send country codes as upper case, two-letter codes according to ISO-3166-1 alpha-2. The client should send codes as upper case.

Country code example

Billing address country field on an Order record.

{
  "billingAddress": {
    ...
    "country": "SE",
    ...
  }
}

Language (language3 code)

Language codes are defined in the ISO-639 standard. The server will always send languages as lower case, three-letter codes according to ISO-639-2. The client may use ISO-639-1 two-letter codes. The client should send codes as lower case.

Language examples

Title fields on a Product record.

{
  ...
  "title_lang": {
    "eng": "Ball bearings",
    "swe": "Kullager"
  },
  "title_lang2": {
    "en": "Ball bearings",
    "sv": "Kullager"
  }
}

Currency (currency code)

Currency codes are defined in the ISO-4217 standard. The server will always send currencies as upper case, three-letter alphabetic codes. The client may send numeric codes.

Currency code example

Total order sum on an Order record.

{
  "totalSumExclTax": {
    ...
    "currency": "SEK"
  }
}

Money

Money field holds monetary data. The structure comprises the following fields:

amount
Contains the actual amount as a decimal value serialized as a string. See Decimal section above.
currency
Contains a currency code, see Currency section above.
decimals
Number of decimals to use. This should be an even number. This is because money usually has an even number of decimals and it allows some smarter logic for guessing the decimal separator (, or .) later down the chain. Thus 2,4,6,8 are fine. 3,5,7 are not. Both currency and amount is required when sending monetary values.

Also read about how to handle taxes in the dedicated Tax chapter.

Money example

Total order sum on an Order record.

{
  "totalSumExclTax": {
    "currency": "SEK",
    "amount": "143.20",
    "decimals": 2
  }
}

Next: Identifiers and references