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

int(n)

Type	Java	MySQL	JavaScript	Notes
int(1)	byte	tinyint	number	signed 1 byte integer, -27 to 27-1
int(2)	short	smallint	number	signed 2 byte integer, -215 to 215-1
int(4)	int	int	number	signed 4 byte integer, -231 to 231-1
int(8)	long	bigint	number	signed 8 byte integer, -263 to 263-1 ⚠️

⚠️ JavaScript number is 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)

float(n)

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
boolean	boolean	tinyint	boolean	MySQL treats 0 as false, non-zero as true

⚠️ JavaScript number is 8 byte float, so only -2⁵³ to 2⁵³-1 is stored with exact precision

---

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

---

Character Types

Character data types offer two encoding options:

• UTF-8 - default encoding, variable length, 1 to 4 bytes per character
• ASCII - subset of UTF-8, fixed length, 1 byte per character

Two SQL types:

• char(n) - data stored in the table, fastest search and index, uses fixed amount of space per row (n * max_bytes_per_character)
• varchar(n) - data stored in the table, fast search and index, uses variable amount of space per row (up to n * max_bytes_per_character)
• text - data stored outside the table, slower search and index, uses only as much space as needed

Two general types:

• string - text is normalized before insertion
  • leading and trailing whitespace is trimmed
  • all internal whitespace is reduced to a single space character
• text - text is inserted as provided

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

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 224 bytes, normalized
utf8text	string	mediumtext	string	up to 224 bytes, not normalized
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 224 bytes, normalized
asciitext	string	mediumtext	string	up to 224 bytes, not normalized

---

Temporal Types

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

• instants - identify specific moment in time, independent of time zone
  • 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):

1. Numeric format (with optional unit suffix)
2. Zoned date-time format (standard calendar)
3. Zoned ordinal date-time format
4. Local date-time format (if timezone provided)
5. Local ordinal date-time format (if timezone provided)
6. 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):

1. Standard calendar date format
2. Ordinal date format
3. 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):

1. Numeric format (with optional unit suffix)
2. Time string format
3. 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):

1. Standard calendar date-time format
2. Ordinal date-time format
3. 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

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>