XBin Format Reference
The XBin (XINA Binary) format provides a XINA standard binary format for time based data files. It uses the file extension xbin.
The xbin format organizes key-value data by time. The data content is a series of rows in ascending time order, with each row having a single microsecond precision Unix time, unique within the file.
Segment Format
XBin data is often encoded in segments, which are defined by an initial signed integer byte length, then that number of bytes. These are referred to in this document as:
- seg1 (up to 127 bytes)
- seg2 (up to 32,767 bytes)
- seg4 (up to 2,147,483,647 bytes)
If the length value of a segment is zero there is no following data and the value is considered empty.
Value Format
Each value starts with a 1 byte signed integer indicating the value type, followed by additional byte(s) containing the value itself, as applicable.
Value Type Definition
| Code | Value | Length | Description |
|---|---|---|---|
0 |
null |
0 | literal null / empty string |
1 |
reference dict index | variable | see below |
2 |
true boolean literal |
0 | |
3 |
false boolean literal |
0 | |
4 |
1 byte signed integer | 1 | |
5 |
2 byte signed integer | 2 | |
6 |
4 byte signed integer | 4 | |
7 |
8 byte signed integer | 8 | |
8 |
4 byte floating point | 4 | |
9 |
8 byte floating point | 8 | |
10 |
string1 | variable | seg1 UTF-8 encoded string |
11 |
string2 | variable | seg2 UTF-8 encoded string |
12 |
string4 | variable | seg4 UTF-8 encoded string |
13 |
json1 | variable | seg1 UTF-8 encoded JSON |
14 |
json2 | variable | seg2 UTF-8 encoded JSON |
15 |
json4 | variable | seg4 UTF-8 encoded JSON |
16 |
xstring1 | variable | seg1 xstring |
17 |
xstring2 | variable | seg2 xstring |
18 |
xstring4 | variable | seg4 xstring |
19 |
xjsonarray1 | variable | seg1 xjson array |
20 |
xjsonarray2 | variable | seg2 xjson array |
21 |
xjsonarray4 | variable | seg4 xjson array |
22 |
xjsonobject1 | variable | seg1 xjson array |
23 |
xjsonobject2 | variable | seg2 xjson array |
24 |
xjsonobject4 | variable | seg4 xjson array |
(-128, -1) |
code dict index | 0 | see below |
XString Format
The xstring value type allows chaining mutliple encoded values to be interpretted as a string. The xstring segment length must be the total number of bytes of all encoded values in the string.
XJSON Array Format
The xjsonarray value type allows chaining mutliple encoded values to be interpretted as a JSON array. The xjsonarray segment length must be the total number of bytes of all encoded values in the array.
XJSON Object Format
The xjsonobject value type allows chaining mutliple encoded values to be interpretted as a JSON object. Each pair of values in the list is interpretted as a key-value pair. The xjsonobject segment length must be the total number of bytes of all encoded key-value pairs in the object. Note that key values must resolve to a string, xstring, number, boolean, or null (which will be interpretted as an empty string key).
Dictionaries
The xbin format provides user-managed compression through the dictionary value types. These come in two flavors, the signed negative type code byte values, and the reference dictionary.
UUID
The file starts with a 16 byte binary encoded UUID. This is intended to uniquely identify the file, but the exact implementation and usage beyond this is not explicitly defined as part of the format definition. For XINA purposes two xbin files with the same UUID would be expected to be identical.
Header
This is followed by a seg4, which contains a single JSON object with UTF-8 encoding. It may be empty. This is currently a placeholder with no defined parameters.
Rows
Each row starts with an 8 byte signed integer containing Unix time with microsecond precision. This is followed by a 4 byte unsigned integer denoting the length of the row in bytes.