Data Types

XINA has a fixed set of data types which apply to attributes and fields. They are intended to provide consistent behavior across MySQL, Java, and JavaScript data types.

Numeric Types

Numeric data types form the backbone of most XINA data sets. Particularly in high data volume environments it is worth considering the smallest byte size type needed, as storage savings and query performance impacts can be considerable.

int(n)

Signed integer values:

Type	Java	MySQL	JavaScript	Notes
`int(1)`	`byte`	`tinyint`	`number`	1 byte signed integer, -2⁷ to 2⁷-1
`int(2)`	`short`	`smallint`	`number`	2 byte signed integer, -2¹⁵ to 2¹⁵-1
`int(4)`	`int`	`int`	`number`	4 byte signed integer, -2³¹ to 2³¹-1
`int(8)`	`long`	`bigint`	`number`	8 byte signed integer, -2⁶³ to 2⁶³-1 ⚠️

⚠️ In JavaScript number primitives are stored as an 8 byte float, so only -2⁵³ to 2⁵³-1 is available with exact precision when working in a JavaScript client (including the XINA web application).

An error is returned if a value provided is outside the range a required type, or contains a fractional value.

float(n)

Standard floating point values:

Type	Java	MySQL	JavaScript	Notes
`float(4)`	`float`	`float`	`number`	IEEE 754 4 byte floating point
`float(8)`	`double`	`double`	`number`	IEEE 754 8 byte floating point

An error will be returned if a floating point value is provided outside the representable magnitude of the required type. (Some languages denote this as Infinity/-Infinity, but this is not supported in XINA). XINA also does not recognize a NaN (not a number) floating point literal.

Boolean Type

Simple true / false type.

Type	Java	MySQL	JavaScript
`boolean`	`boolean`	`tinyint`	`boolean`

Note that MySQL treats 0 as false, non-zero as true.

Character Types

Character data types are used to store text information.

Type	Java	MySQL	JavaScript	Notes
`utf8string(n)`	`string`	`char(n)`	`string`	n up to 128, uses `n*4` bytes, normalized
`utf8vstring(n)`	`string`	`varchar(n)`	`string`	n up to 128, uses up to `n*4` bytes, normalized
`utf8string`	`string`	`mediumtext`	`string`	up to 2²⁴ bytes, normalized
`utf8text`	`string`	`mediumtext`	`string`	up to 2²⁴ bytes, not normalized
`utf8filename`	`string`	`varchar(128)`	`string`	n up to 128, uses up to `n*4` bytes, file-safe characters only
`asciistring(n)`	`string`	`char(n)`	`string`	n up to 256, uses n bytes, normalized
`asciivstring(n)`	`string`	`varchar(n)`	`string`	n up to 256, uses up to n bytes, normalized
`asciistring`	`string`	`mediumtext`	`string`	up to 2²⁴ bytes, normalized
`asciitext`	`string`	`mediumtext`	`string`	up to 2²⁴ bytes, not normalized
`asciifilename`	`string`	`varchar(255)`	`string`	n up to 256, uses up to n bytes, file-safe characters only

Note, all string operations are case-insensitive by default. This can be overridden with the COLLATE expression by specifying a binary collation.

Character Encoding

XINA offers two types of character encoding:

UTF-8

UTF-8 is the recommended default encoding. It has a variable length of 1 to 4 bytes per character.

ASCII

ASCII is recommended for high volume datasets where storage or indexing is critical. It is a subset of UTF-8 with a fixed length of 1 byte per character.

SQL Types

MySQL provides several types for character data storage with different considerations.

char(n)

data stored in the table
fixed amount of space per row (n * max_bytes_per_character)
fastest search and index
requires most storage

varchar(n)

data stored in the table
variable amount of space per row (up to n * max_bytes_per_character)
fast search and index

text

data stored outside the table
slowest search and index
only as much storage as needed

Temporal Types

Temporal data types store time data. ~~There are three categories of temporal types.~~

Instant

~~instants~~ -types identify specific moment in time, independent of time ~~zone~~zone. The value is stored in the database in Unix time, in one of three resolutions:

Type	Java	MySQL	JavaScript
`instant(s)`	`DateTime`	`bigint`	`date`
`instant(ms)`	`DateTime`	`bigint`	`date`
`instant(us)`	`DateTime`	`bigint`	`date`

Additionally, XINA supports standalone date and time components of instants:

Type	Java	MySQL	JavaScript
`date(s)`	`XDate`	`bigint`	`date`
`date(ms)`	`XDate`	`bigint`	`date`
`date(us)`	`XDate`	`bigint`	`date`
`time(s)`	`LocalTime`	`int`	`number`
`time(ms)`	`LocalTime`	`int`	`number`
`time(us)`	`LocalTime`	`bigint`	`number`

The date types are stored as the instant at start of date in UTC, as Unix time. The time types are stored as their respective unit limited to less than 24 hours.

XINA contains the following redundant legacy types, which will deprecated in a future release:

Type	Java	MySQL	JavaScript	Notes
`datetime`	`DateTime`	`bigint`	`date`	replaced by `instant(ms)`
`date`	`XDate`	`bigint`	`date`	replaced by `date(ms)`
`time`	`LocalTime`	`int`	`number`	replaced by `time(ms)`

Local

Local temporal types store values as ISO 8601 formatted strings without a time zone. This has the advantage of being plain-text searchable.

Type	Java	MySQL	JavaScript	Format
`localdate`	`LocalDate`	`char(10)`	`string`	`yyyy-MM-dd`
`localtime(s)`	`LocalTime`	`char(8)`	`string`	`HH:mm:ss`
`localtime(ms)`	`LocalTime`	`char(12)`	`string`	`HH:mm:ss.SSS`
`localtime(us)`	`LocalTime`	`char(15)`	`string`	`HH:mm:ss.SSSSSS`
`localdatetime(s)`	`LocalDateTime`	`char(19)`	`string`	`yyyy-MM-ddTHH:mm:ss`
`localdatetime(ms)`	`LocalDateTime`	`char(23)`	`string`	`yyyy-MM-ddTHH:mm:ss.SSS`
`localdatetime(us)`	`LocalDateTime`	`char(26)`	`string`	`yyyy-MM-ddTHH:mm:ss.SSSSSS`

localdate and localdatetime(*) are directly comparable in the database. A localdate and localtime(*) can be merged into a localdatetime(*) with CONCAT([localdate], 'T', [localtime]).

XINA contains the following redundant legacy types, which will deprecated in a future release:

Type	Java	MySQL	JavaScript	Notes
`localtime`	`LocalTime`	`char(12)`	`string`	replaced by `localtime(ms)`
`localdatetime`	`LocalDateTime`	`char(23)`	`string`	replaced by `localdatetime(ms)`

Duration

instants -
- stored numerically in the database in milliseconds
- datetime and date use Unix epoch
- datetime and date comparable in database
- date + time = datetime
- typically displayed in local time zone in front-end applications
timestamps - identify specific formatted time without time zone consideration (thus local)
- stored as ISO 8601 formatted string in database
- localdate and localdatetime comparable in database
- CONCAT(localdate, 'T', localtime) = localdatetime

Type	Java	MySQL	JavaScript	Notes
`datetime`	`DateTime`	`bigint`	`date`	instant with millisecond precision, as Unix time
`date`	`XDate`	`bigint`	`date`	instant at start of date UTC, as Unix time
`time`	`LocalTime`	`int`	`number`	length of time up to 23:59:59.999, as millisecond count
`localdatetime`	`LocalDateTime`	`char(24)`	`string`	full timestamp without timezone, stored as `string`
`localdate`	`LocalDate`	`char(10)`	`string`	date without timezone, stored as `string`
`localtime`	`LocalTime`	`char(12)`	`string`	length of time up to 23:59:59.999, as `string`

Time Parsing

Unless otherwise indicated, XINA uses standard formats for time parsing wherever possible.

All parsers support multiple separator characters for maximum flexibility:

Date separators: -, _, , .
Time separators: :, _, , .
Date-time separators: T, _, , .
Fraction separators: ., _, , ,

Additionally, all parsers use a strict resolution style with ISO chronology to ensure date validity (e.g., February 30th would be rejected).

Instant Parsing

Numeric Epoch Format

Pattern:

[+-]?digits[unit] where unit is s, ms, us, or ns

Examples:

1609459200 → 2021-01-01T00:00:00Z (auto-detected as seconds)
1609459200s → explicit seconds
1609459200000ms → milliseconds
1609459200000000us → microseconds
1609459200000000000ns → nanoseconds

Auto-Detection Logic (XDateTimeFormatters.java:782-789):

n > 1e16 → nanoseconds
n > 1e14 → microseconds
n > 1e11 → milliseconds
n > 1e8 → seconds
Otherwise → throws DateTimeException

Zoned Date-Time Format

Pattern: {LOCAL_DATE_TIME}{offset}[{zone_id}]
Examples:
- 2011-12-03T10:15:30+01:00 (with offset)
- 2011-12-03T10:15:30Z (UTC)
- 2011-12-03T10:15:30+01:00[Europe/Paris] (with zone ID)

Ordinal Zoned Date-Time Format

Uses ZONED_ORDINAL_DATE_TIME_PARSER (XDateTimeFormatters.java:483-493)

Examples:
- 2011-124T10:15:30+01:00
- 2011-124T10:15:30Z

Local Date-Time (with fallback timezone)

If a timezone is provided as a parameter, local date-times will be interpreted using that zone:

Examples:
- 2011-12-03T10:15:30 → interpreted in provided timezone
- 2011-124T10:15:30 → ordinal format, interpreted in provided timezone

Implementation Details

The parser tries formats in order (XDateTimeFormatters.java:705-732):

Numeric format (with optional unit suffix)
Zoned date-time format (standard calendar)
Zoned ordinal date-time format
Local date-time format (if timezone provided)
Local ordinal date-time format (if timezone provided)
Throws DateTimeException if no match

LocalDate Parsing

Standard Calendar Date Format

Uses LOCAL_DATE_PARSER (XDateTimeFormatters.java:194-202)

Pattern: YYYY[separator]MM[separator]DD
Separators: -, _, (space), .
Examples:
- 2011-12-03 (standard ISO)
- 2011_12_03 (underscore)
- 2011 12 03 (space)
- 2011.12.03 (period)

Ordinal Date Format

Uses LOCAL_ORDINAL_DATE_PARSER (XDateTimeFormatters.java:398-404)

Pattern: YYYY[separator]DDD (day-of-year)
Separators: -, _, , .
Examples:
- 2011-124 (124th day of 2011)
- 2011_124
- 2011 124
- 2011.124

Implementation Details

The parser tries formats in order (XDateTimeFormatters.java:527-540):

Standard calendar date format
Ordinal date format
Throws DateTimeException if neither matches

LocalTime Parsing

Functions

parseOptionalLocalTime(String s) - Returns Optional<LocalTime>
parseLocalTime(UnknownJsonValue v) - JSON variant, supports numeric epoch values
parseOptionalLocalTime(UnknownJsonValue v) - JSON variant

Supported Formats

Time String Format

Uses LOCAL_TIME_PARSER (XDateTimeFormatters.java:281-292)

Pattern: HH[sep]MM[sep]SS[frac_sep]nnnnnnnnn
Time Separators: :, _, , .
Fraction Separators: ., _, , ,
Optional components: seconds, fractional seconds (0-9 digits)
Examples:
- 10:15 (hour and minute only)
- 10:15:30 (with seconds)
- 10:15:30.123456789 (with nanoseconds)
- 10_15_30 (underscore separator)
- 10.15.30,123 (mixed separators)

Numeric Time Format

Supports epoch-based time-of-day values with automatic unit detection:

Numeric Pattern (XDateTimeFormatters.java:84-86):

Pattern: [+-]?digits[unit] where unit is optional: s, ms, us, ns
Examples:
- 3600 → 1:00:00 (auto-detected as seconds)
- 3600s → 1:00:00 (explicit seconds)
- 3600000ms → 1:00:00 (milliseconds)
- 3600000000us → 1:00:00 (microseconds)
- 3600000000000ns → 1:00:00 (nanoseconds)

Auto-Detection Logic (XDateTimeFormatters.java:616-621):

n < 86,400 → seconds
n < 86,400,000 → milliseconds
n < 86,400,000,000 → microseconds
Otherwise → nanoseconds

Implementation Details

The parser tries formats in order (XDateTimeFormatters.java:573-587):

Numeric format (with optional unit suffix)
Time string format
Throws DateTimeException if neither matches

LocalDateTime Parsing

Standard Date-Time Format

Uses LOCAL_DATE_TIME_PARSER (XDateTimeFormatters.java:311-318)

Pattern: {LOCAL_DATE}[dt_sep]{LOCAL_TIME}
Date-Time Separators: T, _, , .
Examples:
- 2011-12-03T10:15:30 (standard ISO)
- 2011-12-03T10:15:30.123456789 (with nanoseconds)
- 2011_12_03_10_15_30 (all underscores)
- 2011-12-03 10:15:30 (space separator)
- 2011.12.03.10.15.30 (all periods)

Ordinal Date-Time Format

Uses LOCAL_ORDINAL_DATE_TIME_PARSER (XDateTimeFormatters.java:423-431)

Pattern: {ORDINAL_DATE}[dt_sep]{LOCAL_TIME}
Examples:
- 2011-124T10:15:30 (ordinal date)
- 2011_124_10_15_30
- 2011-124 10:15:30.123

Implementation Details

The parser tries formats in order (XDateTimeFormatters.java:656-669):

Standard calendar date-time format
Ordinal date-time format
Throws DateTimeException if neither matches

JSON Types

JSON data types store JSON data directly in the database.

Type	Java	MySQL	JavaScript
`jsonarray`	`JsonArray`	`json`	`array`
`jsonobject`	`JsonObject`	`json`	`object`

Enum Types

Enum types map a series of discrete numeric integer values to text names. Though additional values may be added in the future, existing values will not change names or IDs.

`notification_level`

ID	Name	Notes
`0`	`none`	default level, no associated formatting
`1`	`success`	green
`2`	`info`	cyan
`3`	`notice`	yellow
`4`	`warning`	red
`5`	`primary`	blue, elevated over `none`
`6`	`secondary`	grey, below `none`

`notification_type`

ID	Name	Notes
`0`	`post`
`1`	`task`
`2`	`request`	request received
`3`	`response`	response to request received

`post_level`

ID	Name	Notes
`0`	`none`	default level, no associated formatting
`1`	`success`	green
`2`	`info`	cyan
`3`	`notice`	yellow
`4`	`warning`	red
`5`	`primary`	blue, elevated over `none`
`6`	`secondary`	grey, below `none`

Null Value

Although not a discrete XINA data type, null values may appear in any type depending on the context.

Type	Java	MySQL	JavaScript	JSON
`null`	`null`	`NULL`	`null`	`null`, `""` (empty string)

Broadly, the XINA interpretation of a null value is simply "no value". For this reason XINA treats empty strings in JSON as equivalent to null (because they contain no actual information). The implication of this concept in SQL is that operations on null values return null:

null + 1 → null
null == null → null

Record Formatting

UNDER CONSTRUCTION, details may change

A record can be formatted to a string by wrapping each field name in brackets. For example, the record:

{ "foo": "bar" }

with the format:

"Foo: {foo}"

would resolve to "Foo: bar".

Additionally, values can be passed through pipes, allowing custom formatting to be used, or modifying the value entirely. The pipe format is:

| @<pipe name> <pipe args>

Data Types

Numeric Types

int(n)

float(n)

Boolean Type

Character Types

Character Encoding

UTF-8

ASCII

SQL Types

char(n)

varchar(n)

text

Categories

string

text

filename

Temporal Types

Instant

Local

Duration

Time Parsing

Instant Parsing

Numeric Epoch Format

Zoned Date-Time Format

Ordinal Zoned Date-Time Format

Local Date-Time (with fallback timezone)

Implementation Details

LocalDate Parsing

Standard Calendar Date Format

Ordinal Date Format

Implementation Details

LocalTime Parsing

Functions

Supported Formats

Time String Format

Numeric Time Format

Implementation Details

LocalDateTime Parsing

Standard Date-Time Format

Ordinal Date-Time Format

Implementation Details

JSON Types

Enum Types

notification_level

notification_type

post_level

Null Value

Record Formatting

`notification_level`

`notification_type`

`post_level`