Struct Definitions Reference

This page provides a reference for the purpose and structure of all structs standard groups and databases.

Structs groups and databases are marked with a JSON object using the key xs_struct. This contains three standard parameters:

"type" - the name of the type of struct element as a string
"v" - the current version this instance of the specified type as a string
"conf" - optional JSON object, format depends on type

Versioning is tied to the version number of the XINA server. Typically server updates will automatically apply needed changes to all structs schema elements, incrementing their "v" property to the latest version. In the event an upgrade cannot be performed the version will not be changed.

Groups

Note that group versioning is used to manage databases required within groups.

Project

Top level struct group. All struct groups and databases must be decendants of a project to be recognized. Name and label are customizable.

Created with the STRUCT CREATE PROJECT action.

Struct Parameters

Parameter	Value
type	`"project"`

Group Parameters

Parameter	Value
name	*
label	*

Parameter	Value
type	`"category"`

Model

Group for which all data is locally co-relevant. Must be a child of either a project or category group. Name and label are customizable.

Created with the STRUCT CREATE MODEL action.

Struct Parameters

Parameter	Value
type	`"model"`

Group Parameters

Parameter	Value
name	*
label	*

Pipe

Group for all data from a single pipe. Must be the child of a model group. Name and label are customizable.

Created with the STRUCT CREATE PIPE action.

Struct Parameters

Parameter	Value	Default
type	`"pipe"`

Conf Parameters

Parameter	Value	Default
discrete	boolean	`false`
buffer	boolean	`false`
variable	boolean	`false`
t	archive length in minutes	`60`

Group Parameters

Parameter	Value
name	*
label	*

Notes

If discrete is true, mnemonic data is not considered persistent between archives, and open/close interval operations are not supported.

If buffer is true, the mn_buffer database will be generated, and the pipe will be included in automated archive tasks. Otherwise, the STRUCT BUFFER IMPORT action will not be supported.

If variable is true, mnemonic and event databases in the pipe will include the archive ID field (a_id). If buffer is true, variable must be false (since buffer-generated archives cannot be variable).

t specifies the archive length in minutes, if variable is false. This cannot be changed. The default is 60 minutes (1 hour). A shorter window may be appropriate for very high data volumes. The maximum is 1440 (24 hours), and the value must be evenly divisible into 1440.

Changelog

11.0.0 (planned)

renamed from origin to pipe

Definitions

Group containing definitions databases.

Struct Parameters

Parameter	Value
type	`"def"`

Group Parameters

Parameter	Value
name	`"def"`
label	`"Definitions"`

Changelog

11.0.0 (planned)

add filter definitions database

Task

Group containing task tracking databases. Must be a child of a pipe group.

Struct Parameters

Parameter	Value
type	`"task"`

Group Parameters

Parameter	Value
name	`"task"`
label	`"Task"`

Mnemonic

Group containing mnemonic data databases. Must be a child of a pipe group.

Struct Parameters

Parameter	Value
type	`"mn"`

Group Parameters

Parameter	Value
name	`"mn"`
label	`"Mnemonic"`

Mnemonic Bin

Group containing binned mnemonic data databases. Must be a child of a mnemonic group.

Struct Parameters

Parameter	Value
type	`"mn_bin"`

Group Parameters

Parameter	Value
name	`"bin"`
label	`"Bin"`

Databases

Structs databases typically specify a set of required fields, and may permit the inclusion of additional custom fields. Changes to the spec involving fields will usually be treated as minor version changes, though they may require manual user correction if an added field conflicts with a custom field already present in a particular database instance.

Note that fields marked as virtual are calculated from the values of other field(s) and cannot be populated or edited manually.

Definitions

All definitions databases must be direct children of a definitions group, and all definitions groups must contain one of each definition database.

Diagram Definitions

Holds diagram definitions. The diagram itself is in an attached SVG file.

Struct Parameters

Parameter	Value
type	`"def_diagram"`

Database Parameters

Parameter	Value
name	`"diagram"`
label	`"Diagram"`
format	`"{name}"`
order	(`name`, desc)
singular	`"diagram"`

Fields

Name	Type	Req	Description
name	`utf8vstring(128)`	✓	unique conf name
file_name	`utf8filename`	✓	file name
conf	`jsonobject`		diagram configuration
meta	`jsonobject`		additional metadata as needed

Changelog

11.0.0 (planned)

order changed to (name, asc)
added desc field

Event Definitions

Holds event definitions, specifying how they are displayed, interpretted and processed.

Struct Parameters

Parameter	Value
type	`"def_event"`

Database Parameters

Parameter	Value
name	`"event"`
label	`"Event"`
format	`"{name}"`
order	(`name`, asc)
singular	`"event definition"`

Fields

Name	Type	Req	Description
e_id	`int(4)`	✓	unique ID
name	`utf8vstring(128)`	✓	unique name
desc	`utf8text`		plain text description
meta	`jsonobject`		additional arbitrary metadata
conf	`jsonobject`		configuration for pseudo-events
aliases	set(utf8string)		alternative name(s)
ext_id	`asciistring`		external ID

Changelog

11.0.0 (planned)

added ext_id field
removed type field
changed e_id type from int(8) to int(4)

Filter Definitions

Provisional, not yet implemented

Holds mnemonic filter definitions.

Struct Parameters

Parameter	Value
type	`"def_filter"`

Database Parameters

Parameter	Value
name	`"filter"`
label	`"Filter"`
format	`"{name}"`
order	(`name`, asc)
singular	`"filter definition"`

Fields

Name	Type	Req	Description
filter_id	`int(4)`	unique ID
name	`utf8vstring(128)`	✓	unique name
desc	`utf8text`		plain text description
condition	`jsonobject`	✓	filter condition definition
t_start_offset	`duration(us)`	✓	start time offset (`0` if not provided)
t_end_offset	`duration(us)`	✓	end time offset (`0` if not provided)
meta	`jsonobject`		additional metadata as needed
ext_id	`asciistring`		external ID

Changelog

11.0.0 (planned)

initial release

Mnemonic Definitions

Holds mnemonic definitions, specifying how they are displayed, interpretted and processed.

Struct Parameters

Parameter	Value
type	`"def_mn"`

Database Parameters

Parameter	Value
name	`"mn"`
label	`"Mnemonic"`
format	`"{name} ({unit})"`
order	(`name`, asc)
singular	`"mnemonic definition"`

Fields

Name	Type	Req	Description
mn_id	`int(4)`	✓	unique ID
name	`utf8vstring(128)`	✓	unique name
subname	`utf8vstring(32)`		mnemonic sub-name
desc	`utf8text`		plain text mnemonic description
unit	`utf8vstring(32)`		measurement unit (for example, `"V"`, `"mA"`)
state	`struct_mn_state`	✓	current state of mnemonic
pipes	`jsonobject`	✓	map of model(s) to associated pipe(s)
full	`asciivstring(32)`		the primary database for the mnemonic, default `f8`
bin	`set(asciistring)`		the opt-in bin database(s) to include the mnemonic in
format	`asciivstring(32)`		printf-style format to render values
enums	`jsonobject`		mapping of permitted text values to numeric values
labels	`list(jsonobject)`		mapping of numeric values or ranges to labels
aliases	`set(utf8string)`		set of additional names associated with the mnemonic
meta	`jsonobject`		additional metadata as needed
query	`asciivstring(32)`		query name for pseudo-mnemonics
conf	`jsonobject`		configuration for pseudo-mnemonics
ref	`int(4)`		reference mnemonic ID
ext_id	`asciistring`		external ID

Changelog

11.0.0

added subname field
added ref field
added ext_id field
origins changed to pipes

1.0.0

enum changed to enums since "enum" is often a reserved keyword
meas field removed (measure now assumed from unit)

Mnemonic Tracking

Used for tracking mnemonic selection activity. Although this is not strictly a definitions database, it is tightly coupled to the mnemonic definitions database, and is thus defined in the definitions context.

Struct Parameters

Parameter	Value
type	`"def_mn_track"`

Database Parameters

Parameter	Value
name	`"mn_track"`
label	`"Mnemonic Tracking"`
format	`"{t} {mn_id} {user}"`
order	(`name`, asc)
singular	`"mnemonic definition"`

Fields

Name	Type	Req	Description
t	`instant(us)`	✓	time of selection
mn_id	`int(4)`	✓	mnemonic ID selected
user	`user_id`	✓	user taking action
mns	`set(int(4))`		other mnemonic ID(s) selected
models	`set(asciistring)`		model(s) in current context

Changelog

11.0.0 (planned)

rename mn_ids to mns
order changed to (t, desc)
format changed to "{t} {mn_id} {user}"

Nominal Definitions

Holds mnemonic nominal range definitions.

Struct Parameters

Parameter	Value
type	`"def_nominal"`

Database Parameters

Parameter	Value
name	`"nominal"`
label	`"Nominal"`
format	`"{mn_id} {color} ({min}, {max}) {label}"`
order	(`mn_id`, asc), (`label`, asc)
singular	`"nominal definition"`

Fields

Name	Type	Req	Description
unid	`uuid`	✓	unique nominal range ID
mn_id	`int(4)`	✓	unique mnemonic ID
label	`utf8vstring(128)`	✓	nominal range label
desc	`utf8text`		plain text nominal range description
color	`struct_nominal_color`		range color indicator
min	`float8`		min value for the range
max	`float8`		max value for the range
models	`set(asciistring)`		models for which this range should apply (all if `null`)

Notes

The struct_nominal_color type is an enum of green (0), yellow (1), and red (2).

Changelog

11.0.0 (planned)

renamed "nominal_id" to "unid"

Plot Configuration Definitions

Holds mnemonic plot configuration definitions.

Struct Parameters

Parameter	Value
type	`"def_plot"`

Database Parameters

Parameter	Value
name	`"plot"`
label	`"Plot Conf"`
format	`"{name}"`
order	(`name`, asc)
singular	`"plot configuration"`

Fields

Name	Type	Req	Description
name	`utf8vstring(128)`	✓	unique conf name
desc	`utf8text`		plain text conf description
conf	`jsonobject`	✓	configuration
models	`set(asciistring)`		models for which this conf should apply (any if `null`)

Changelog

11.0.0 (planned)

conf changed from jsonobject to struct_plot_conf

Profile Definitions

Holds mnemonic profile definitions.

Struct Parameters

Parameter	Value
type	`"def_profile"`

Database Parameters

Parameter	Value
name	`"profile"`
label	`"Profile"`
format	`"{name}"`
order	(`name`, asc)
singular	`"profile"`

Fields

Name	Type	Req	Description
name	`utf8vstring(128)`	✓	unique conf name
desc	`utf8text`		plain text profile description
models	`set(asciistring)`		models for which this conf should apply (all if `null`)
data	`jsonobject`	✓	profile data configuration
plot	`jsonobject`		profile plot configuration

Notes

Requires review before use.

Changelog

11.0.0 (planned)

conf changed from jsonobject to struct_plot_conf

Trend Definitions

Provisional, not yet implemented

Holds mnemonic trend definitions.

Struct Parameters

Parameter	Value
type	`"def_trend"`

Database Parameters

Parameter	Value
name	`"trend"`
format	`"Trend"`
order	(`name`, asc)
singular	`"trend definition"`

Fields

Name	Type	Req	Description
name	`utf8vstring(128)`	✓	unique trend name
desc	`utf8text`		plain text trend description
profiles	`set(utf8string)`		profile name(s) to include in trend
t	`list(jsonobject)`		time range(s) to include
intervals	`jsonarray`		intervals to include/omit
plot	`jsonobject`		plot configuration

Files

Parameter	Value
type	`"file_archive"`

Mn File Buffer

Contains all mnemonic buffer files for an origin. Must be a child of an origin group.

Struct Parameters

Parameter	Value
type	mn_file_buffer
v	1.0.0

Database Parameters

Parameter	Value
name	`"buffer"`
label	`"Buffer"`
format	`"{file_name}"`
singular	`"buffer file"`

Fields

Name	Type	Req	Description
uuid	`uuid`	✓	file UUID
file_name	`utf8filename`	✓	buffer file name
t_min	`instant(us)`	✓	time of first data in file
t_max	`instant(us)`	✓	time of last data in file
dur	`duration(us)`	✓	virtual duration in microseconds
state	`struct_buffer_state`	✓	buffer file state
flag	`struct_buffer_flag`		buffer file flag
format	`asciivstring(32)`		buffer file format (default `"csv"`)
conf	`jsonobject`		configuration for format as needed

Notes

The state field may be one of four values:

PENDING - the file data is present in the mnemonic buffer database but has not been processed further
PROCESSED - the file has been converted into a standard xbin file format
ARCHIVED - the file contents have been distributed to the appropriate archive file(s)
DEPRECATED - the file is preserved but no longer included in archive files

The flag field may be one of two values:

DEPRECATE - the file is queued for deprecation
DELETE - the file is queued for deletion

Events

Event databases come in three forms, simple events, single file per event, and multiple files per event.

Event

Each record is a single event. May be a child of either a model or pipe group.

Struct Parameters

Parameter	Value
type	`"event"`

Database Parameters

Parameter	Value
name	* (default `"event"`)
label	* (default `"Event"`)
format	* (default `"{t_start} {event_id} {label}"`)
order	* (default (`t_start`, desc), (`event_id`, asc))
singular	* (default `"event"`)

Fields

Name	Type	Req	Virtual	Description
ueid	`uuid`	✓		event UUID
e_id	`int(4)`	✓		event ID (default to `0` if not provided)
t_start	`instant(us)`	✓		start time
t_end	`instant(us)`			end time (if `null`, event is an open interval)
dur	`duration(us)`	✓	✓	duration in microseconds (`null` if open)
interval	`boolean`	✓	✓	`t_start` != `t_end`
open	`boolean`	✓	✓	`t_end` is `null`
type	`struct_event_type`	✓		event type (default to `message` if not provided)
level	`struct_event_level`	✓		event level (default to `none` if not provided)
label	`utf8vstring(128)`	✓		plain text label
content	`utf8text`			extended event content
meta	`jsonobject`			additional metadata as needed
conf	`jsonobject`			configuration for specific event types

Notes

Virtual fields are calculated from other fields and cannot be populated manually.

Changelog

11.0.0

changed uuid to ueid
changed e_id type from int(8) to int(4)
removed name field

1.0.2

corrected t_end and dur as not required

1.0.1

corrected name as not required

1.0.0

pid (primary ID) changed to e_id (event ID) to avoid confusion
sid removed (additional IDs may be added as needed)
int changed to interval (int is commonly reserved keyword)
dur, interval, and open are now derived fields from t_start and t_end
added struct_event_type and struct_event_level data types
added name as event definition association

Event File

Uses same structure as event database, with one additional field.

Database Parameters

Parameter	Value
name	* (default `"eventf"`)
label	* (default `"Event File"`)
singular	* (default `"event file"`)

Name	Type	Req	Description
file_name	`utf8filename`	✓	file name

Event Files

Uses same structure as event database, but with a child file database, allowing each event to contain zero or more files.

Database Parameters

Parameter	Value
name	* (default `"eventfs"`)
label	* (default `"Event Files"`)
singular	* (default `"event files"`)

Event Change

Captures changes to events as records.

Struct Parameters

Parameter	Value
type	`"event_change"`

Database Parameters

Parameter	Value
name	`"{name}_change"`)
label	`"{label} Change"`
format	`"{t_start} {event_id} {label}"`)
order	(`t`, desc)
singular	`"event change"`

Fields

Name	Type	Req	Virtual	Description
t	`instant(us)`	✓		event change time
ueid	`uuid`			event UUID (if change applies to single event)
change	`struct_event_change`	✓	change type
events	`jsonarray`

Mnemonic Databases

Contain mnemonic data. Unless otherwise indicated, mnemonic databases can be configured with a paritioning system which subdivides the tables internally into UTC calendar months. This is beneficial for selective mnemonic data repopulation, since each month can be instantly erased before being regenerated, and doesn't require downtime of the entire dataset. At creation time a start and end year must be specified, and partitions will be created for each month in that range. Data with timestamps outside the range will be stored in either a pre-range or post-range partition as applicable.

Mn Full

Each record is a single mnemonic data point. The data type for mnemonic values is configurable, and determines the database name. By default the mnemonic data group will contain a full float8 database.

Struct Parameters

Parameter	Value
type	mn_full
v	1.0.0
conf.type	numeric data type

Database Parameters

Parameter	Value
name	`"i1"`, `"i2"`, `"i4"`, `"i8"`, `"f4"`, or `"f8"`
label	`"Full {conf.type}"`
format	`"{t} {mn_id} {v}"`
singular	`"mnemonic datapoint"`

Fields

Name	Type	Req	Description
t	`instant(us)`	✓	time
mn_id	`int(4)`	✓	unique mnemonic ID
v	`{conf.type}`		value

Mn Buffer

Each record is a single mnemonic data point. Holds data imported through the buffer pipeline. Unlike other mnemonic databases, may contain duplicate data points.

This database does not hold data indefinitely. The automated archive pipeline will remove data as it is archived and mined into the primary mnemonic databases.

Struct Parameters

Parameter	Value
type	mn_buffer
v	1.0.0

Database Parameters

Parameter	Value
name	`"buffer"`
label	`"Buffer"`
format	`"{t} {mn_id} {v}"`
singular	`"mnemonic buffer datapoint"`

Fields

Name	Type	Req	Description
t	`instant(us)`	✓	time
mn_id	`int(4)`	✓	unique mnemonic ID
v	`{conf.type}`		value

Mn Delta

An optimized mnemonic storage solution with each record representing one or more mnemonic data points, by only including points where the mnemonic value actually changes. The value data type is customizable, as with the Mn Full database. By default the mnemonic data group will contain a delta float8 database.

Struct Parameters

Parameter	Value
type	mn_delta
v	1.0.0
conf.type	numeric data type

Database Parameters

Parameter	Value
name	`"di1"`, `"di2"`, `"di4"`, `"di8"`, `"df4"`, or `"df8"`
label	`"Delta {conf.type}"`
format	`"{t} {mn_id} {v} ({n})"`
singular	`"mnemonic delta datapoint"`

Fields

Name	Type	Req	Description
t	`instant(us)`	✓	time
mn_id	`int(4)`	✓	unique mnemonic ID
v	`{conf.type}`		value
n	`int(4)`	✓	number of datapoints included in this point

Mn Bin Time

Contains mnemonic data binned on fixed time intervals. By default these will be created for 1 minute ("t60") and 10 minute ("t600") bin sizes.

Struct Parameters

Parameter	Value
type	mn_bin_time
v	1.0.0
conf.t	bin size in seconds

Database Parameters

Parameter	Value
name	`"t{conf.t}"`
label	`"Time ({conf.t}s)"`
format	`"{t} {mn_id} {avg} ({min}, {max})"`
singular	`"mnemonic bin"`

Fields

Name	Type	Req	Description
t	`instant(us)`	✓	start time
mn_id	`int(4)`	✓	unique mnemonic ID
t_min	`instant(us)`	✓	time of first datapoint
t_max	`instant(us)`	✓	time of last datapoint
n	`int(4)`	✓	number of datapoints in bin
avg	`float(8)`	✓	average
min	`float(8)`	✓	min
max	`float(8)`	✓	max
med	`float(8)`	✓	median
var	`float(8)`	✓	sample variance
std	`float(8)`	✓	sample standard deviation

Mn Bin Interval

Contains mnemonic data binned by interval events.

Struct Parameters

Parameter	Value
type	mn_bin_interval
v	1.0.0

Database Parameters

Parameter	Value
name	`"interval"`
label	`"Interval"`
format	`"{t} {e_id} {mn_id} {avg} ({min}, {max})"`
singular	`"mnemonic bin"`

Fields

Name	Type	Req	Description
uuid	`uuid`	✓
e_id	`int(8)`	✓
t_start	`instant(us)`	✓	start time
t_end	`instant(us)`	✓	start time
mn_id	`int(4)`	✓	unique mnemonic ID
t_min	`instant(us)`	✓	time of first datapoint
t_max	`instant(us)`	✓	time of last datapoint
n	`int(4)`	✓	number of datapoints in bin
avg	`float(8)`	✓	average
min	`float(8)`	✓	min
max	`float(8)`	✓	max
med	`float(8)`		median
var	`float(8)`		sample variance
std	`float(8)`		sample standard deviation

Task Databases

Store logs and associated files for data processing tasks.

Archive Task

Each record logs a single execution of an archive task.

Struct Parameters

Parameter	Value
type	task_archive
v	1.0.1

Database Parameters

Parameter	Value
name	`"archive"`
label	`"Archive"`
format	`"{task_id} {t}"`
singular	`"archive task"`

Fields

Name	Type	Req	Description
task_id	`task_id`	✓	unique task ID
t	`instant(us)`	✓	time when task submitted
meta	`jsonobject`		additional metadata as needed
conf	`jsonobject`		task configuration
archives	`list(jsonobject)`		archives updated
archived	`list(jsonobject)`		buffer file(s) archived
processed	`list(jsonobject)`		buffer file(s) processed
restored	`list(jsonobject)`		buffer file(s) restored
deprecated	`list(jsonobject)`		buffer file(s) deprecated
deleted	`list(jsonobject)`		buffer file(s) deleted

Mine Task

Each record logs a single execution of a mine task.

Struct Parameters

Parameter	Value
type	task_mine
v	1.0.0

Database Parameters

Parameter	Value
name	`"mine"`
label	`"Mine"`
format	`"{task_id} {t_start}"`
singular	`"mine task"`

Fields

Name	Type	Req	Description
task_id	`task_id`	✓	unique task ID
t	`instant(us)`	✓	time when task submitted
uuid	`uuid`	✓	source archive file UUID
t_start	`instant(us)`	✓	source archive file start time
t_end	`instant(us)`	✓	source archive file end time
meta	`jsonobject`		additional metadata as needed
conf	`jsonobject`		task configuration

Spectra

The spectra definition is a property for event databases.

Property	Value	Req	Description
tabs	array of tab conf(s)		custom tabs for UI
presearch	array of presearch confs		custom pre-search components for UI
filters	array of filter confs
grouping	array of field name(s)
charts	charts conf	✓
tables	array of table conf
query	query conf
labels	labels conf

Spectra Tab Conf

Configuration for a spectra search tab. This may be a string, referencing the name of a custom tab implementation, or an object with a "type" property specifying a tab type and additional properties applicable for that type. Currently there are no custom tab types, but they may be added in the future.

Spectra Database Tab

Under Construction

The database tab employs a record search for a separate target database of any type, and a solution for converting a selection from the target database to the spectra database.

Property	Value	Req	Description
type	`"database"`	✓	tab type name
database	database specifier	✓	target database specifier
map	see below	✓	solution to map target selection to spectra selection

The "map" property may be a string, array of strings, or object.

If a string, the value must be the name of a custom selection function (none currently exist, they may be added in the future).

Spectra Presearch Conf

Specifies a set of components to display before the main spectra search component.

Spectra Field Presearch

Specifies a standalone component to search a particular field.

Property	Value	Req	Description
type	`"field"`	✓	presearch type name
field	field specifier	✓
options	see below		options for search dropdown

Spectra Filters Conf

Specifies filters / badges for spectra search.

Property	Value	Req	Description
name	`string`	✓	system name for filter
label	`string`		display label (uses name if absent)
badge	`string`		badge label (uses name if absent)
desc	`string`		description for badge / filter tooltip
color	`string`		color code or CSS class
e	`expression`	✓	expression to apply for filter

Spectra Charts Conf

Specifies options for each spectra chart.

Property	Value	Req	Description
summary	spectra chart conf	✓	summary chart conf
spectra	spectra chart conf	✓	spectra chart conf

Spectra Chart Conf

Specifies options for a single spectra chart.

Property	Value	Req	Description
x	`string[]`	✓	x axis options
y	`string[]`	✓	y axis options
tooltip	`string`		record format string

Spectra Tables Conf

Under Construction

Spectra Query Conf

Under Construction

Spectra Labels Conf

Labels are specified as an object mapping standard label values to custom values. These will be defined as needed.

Struct Definitions Reference

Groups

Project

Category

Model

Pipe

Definitions

Task

Mnemonic

Mnemonic Bin

Databases

Definitions

Diagram Definitions

Event Definitions

Filter Definitions

Mnemonic Definitions

Mnemonic Tracking

Nominal Definitions

Plot Configuration Definitions

Profile Definitions

Trend Definitions

Files

Archive

Mn File Buffer

Events

Event

Event File

Event Files

Event Change

Mnemonic Databases

Mn Full

Mn Buffer

Mn Delta

Mn Bin Time

Mn Bin Interval

Task Databases

Archive Task

Mine Task

Spectra