Data Types Representation
Data Types Representation
Monospace maps internal system types and database types to uniform JSON representations in the API. While primitive types like strings, booleans, and floats maintain their standard JSON equivalents, certain types are handled specifically to guarantee precision and standardized formatting.
Type Mappings Overview
When querying data or submitting mutations, the following API mappings apply:
| Internal Type | JSON Type | Description |
|---|---|---|
String | String | Standard text string. |
Integer (i64) | Number | 64-bit signed integer. |
UInteger (u64) | Number | 64-bit unsigned integer. |
Float (f64) | Number | Standard IEEE 754 floating point number. |
Decimal | String | Arbitrary-precision decimals are serialized as strings to prevent floating-point rounding errors. |
Boolean | Boolean | True or false. |
Bytes | String | Binary data is serialized as a base64 encoded string. |
JSON | String | JSON column types from the database are serialized as a standalone JSON string. You will need to parse this string (JSON.parse()) on the client side. |
Date | String | Formatted as YYYY-MM-DD. |
Time | String | Formatted as HH:MM:SS (may include fractional seconds, e.g., HH:MM:SS.sss). |
DateTime | String | ISO 8601 formatted without timezone (e.g., YYYY-MM-DDTHH:MM:SS). May include fractional seconds. |
DateTimeZ | String | ISO 8601 formatted with timezone offset (e.g., YYYY-MM-DDTHH:MM:SS.sssZ). |
UUID | String | Standard UUID string. |
Timestamps & Timezones
The DateTime type does not contain timezone information.
Monospace DateTime types are natively parsed and stored as "Naive" DateTimes. When receiving timestamps from the API, they will be formatted as strings without an offset (e.g., 2024-05-12T10:30:00).
It is up to your application to interpret these naive timestamps, generally implying they represent UTC unless you've designed your project's data model differently.
If you need timezone-aware timestamps, use the DateTimeZ type, which stores and returns timestamps with timezone information (e.g., 2024-05-12T10:30:00Z).
JSON Serialization Details
Decimal Types
Decimals, often used for currency or precise measurements, are returned as strings.
JSON Fields
If you have a field in your project configured as a JSON data type, the API payload will contain a string representation of that JSON, rather than an embedded JSON object.
- Response Example:
"{\"key\": \"value\"}"instead of{"key": "value"}. - Input Example: When mutating a JSON field, you must provide the stringified JSON value.