Data Types Representation

Every field has a type that decides its JSON representation in API requests and responses. Most types map to their natural JSON equivalent. 64-bit integers and decimals are strings, so JSON number parsing never rounds them.

Type Mappings

The table shows how each field type appears in responses. Requests use the same representations; the sections below note where inputs differ.

A field with no value is returned as null, regardless of its type.

Integers

Integer fields of 32 bits or fewer are JSON numbers. 64-bit integer fields (int64, uint64) are decimal strings (e.g., "-42").

JavaScript's JSON.parse reads every number as a 64-bit float, which holds integers exactly only up to Number.MAX_SAFE_INTEGER (9007199254740991). Parsing can silently round any integer outside ±Number.MAX_SAFE_INTEGER — 9007199254740993 becomes 9007199254740992. A string keeps every digit.

The field's type decides the representation, not the value. An int64 field returns "42", never 42.

This response shows an Articles item with a word_count field of type int32 and a view_count field of type int64:

{
  "data": {
    "id": 1,
    "word_count": 1250,
    "view_count": "9007199254740993"
  }
}

Convert a 64-bit value with BigInt() when you need to do arithmetic on it:

const views = BigInt(article.view_count)

Requests accept a 64-bit value as a string or a number. Send a string for any value outside ±Number.MAX_SAFE_INTEGER — a JavaScript number has already lost precision before it reaches the API.

The SDK types 64-bit fields as string in responses and as string | number in inputs.

Decimals

decimal fields are strings (e.g., "19.99") so arbitrary-precision values survive without floating-point rounding. Use them for currency and other exact quantities, and send them as strings.

float32 and float64 fields are JSON numbers. Non-finite values (NaN, Infinity) are returned as null.

Dates and Times

Responses include fractional seconds only when they are nonzero, with 3, 6, or 9 digits (e.g., 10:30:00.250). A zero offset is written as Z.

dateTime values carry no timezone. Monospace attaches none, and your application decides which timezone they represent. Use dateTimeWithTimezone when a timestamp must identify an exact instant.

JSON Fields

A json field is embedded in the payload as native JSON — an object, array, string, number, boolean, or null — in both requests and responses. Monospace does not wrap it in a string.

{
  "data": {
    "id": 1,
    "metadata": { "tags": ["release", "api"], "featured": true }
  }
}

Binary Data

bytes fields are standard base64-encoded strings (RFC 4648, with padding) in both requests and responses.