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 will always contain at least two members:

"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

The version allows structs elements to be upgraded as the structs definitions evolve. It uses a basic semantic versioning format, specifically MAJOR.MINOR.PATCH, where:

MAJOR changes indicate breaking structural changes
MINOR changes add functionality in a backward compatible manner
PATCH changes make backward compatible bug fixes

Minor and patch changes will automatically be applied to structs elements in server upgrades, whereas major changes will typically require user interaction. Major changes will be avoided as much as possible to maintain stable workflows. Patch version updates will only be used in cases where a change was needed to correctly adhere to the documented specifications on this page.

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.

Group Parameters

Parameter	Value
name	*
label	*

Struct Parameters

Parameter	Value
type	project
v	1.0.0

Parameter	Value
type	category
v	1.0.0

Model

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

Created with the STRUCT CREATE MODEL action.

Group Parameters

Parameter	Value
name	*
label	*

Struct Parameters

Parameter	Value
type	model
v	1.0.0

Origin

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

Created with the STRUCT CREATE ORIGIN action.

Group Parameters

Parameter	Value
name	*
label	*

Struct Parameters

Parameter	Value
type	origin
v	1.0.0

Definitions

Group containing definitions databases.

Group Parameters

Parameter	Value
name	def
label	Definitions

Struct Parameters

Parameter	Value
type	origin
v	1.0.0

Task

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

Group Parameters

Parameter	Value
name	task
label	Task

Struct Parameters

Parameter	Value
type	task
v	1.0.0

Mnemonic

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

Group Parameters

Parameter	Value
name	mn
label	Mnemonic

Struct Parameters

Parameter	Value
type	mn
v	1.0.0

Mnemonic Bin

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

Group Parameters

Parameter	Value
name	mn_bin
label	Bin

Struct Parameters

Parameter	Value
type	mn_bin
v	1.0.0

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.

Definitions

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

Event Definitions

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

Database Parameters

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

Struct Parameters

Parameter	Value
type	def_event
v	1.0.0

Fields

Name	Type	Req	Description
event_id	`int(4)`	✓	unique event ID
name	`utf8vstring(128)`	✓	unique event name
desc	`utf8text`		plain text event description
meta	`jsonobject`		additional arbitrary metadata
conf	`jsonobject`		configuration for pseudo-mnemonics

Mnemonic Definitions

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

Database Parameters

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

Struct Parameters

Parameter	Value
type	def_mn
v	1.0.0

Fields

Name	Type	Req	Description
mn_id	`int(4)`	✓	unique mnemonic ID
name	`utf8vstring(128)`	✓	unique mnemonic name
desc	`utf8text`		plain text mnemonic description
unit	`utf8vstring(32)`		measurement unit (for example, `"V"`, `"mA"`)
state	`struct_mn_state`	✓	current state of mnemonic
origins	`jsonobject`	✓	map of model(s) to associated origin(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

Notes

Changelog

1.0.0

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

Nominal Def

Holds mnemonic nominal range definitions.

Database Parameters

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

Struct Parameters

Parameter	Value
type	def_nominal
v	1.0.0

Fields

Name	Type	Req	Description
nominal_id	`uuid`	✓	unique nominal range ID
mn_id	`int(4)`	✓	unique mnemonic ID
label	`utf8vstring(128)`	✓	nominal range label
desc	`utf8text`		plain text ~~event~~nominal range description
color	`struct_nominal_color`		additional arbitrary metadata
~~conf~~min	`jsonobjectfloat8`		~~configuration~~min value for ~~pseudo-mnemonics~~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

1.1.0 (planned)

label changed to name for consistency with other structs databases

Plot Def

Holds mnemonic plot configuration definitions.

Database Parameters

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

Struct Parameters

Parameter	Value
type	def_plot
v	1.0.0

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`)

Notes

Changelog

1.1.0 (planned)

conf changed from jsonobject to struct_plot_conf

Profile Def

Diagram Def

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 direct child of either a model or origin:

...<model>.event or ...<origin>.event

Parameter	Value
type	event
version	1.0.1
name	event
label	Event

Fields

Note that virtual fields are calculated from other fields and cannot be populated manually.

Name	Type	Req	Description
uuid	`uuid`	✓	event UUID
e_id	`int(8)`	✓	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)`	✓	virtual duration in microseconds (`null` if open)
interval	`boolean`	✓	virtual `t_start` != `t_end`
open	`boolean`	✓	virtual `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)
name	`utf8vstring(128)`		event name (if associated with event definition)
label	`utf8vstring(128)`	✓	plain text label
content	`utf8text`		extended event content
meta	`jsonobject`		additional metadata as needed
conf	`jsonobject`		configuration for specific event types

Changelog

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.

Name	Type	Req	Description
file_name	`utf8filename`	✓	safe file name

Event Files

Mnemonics

Mn Full

Mn Buffer

Mn Delta

Mn Bin Time

Mn Bin Interval

Mn File Archive

Contains all mnemonic archive files for an origin. Parent must be an origin group:

...<origin>.archive

Parameter	Value
type	archive
version	1.0.0
name	archive
label	Archive

Fields

Name	Type	Req	Description
uuid	`uuid`	✓	file UUID
t_start	`instant(us)`	✓	start time
t_end	`instant(us)`	✓	end time
dur	`duration(us)`	✓	virtual duration in microseconds
t_min	`instant(us)`	✓	time of first data in file
t_max	`instant(us)`	✓	time of last data in file
file_name	`utf8filename`	✓	archive file name
format	`asciivstring(32)`		file format (default `"xbin"`)
meta	`jsonobject`		additional metadata as needed
conf	`jsonobject`		configuration for format as needed

Mn File Buffer

Contains all mnemonic buffer files for an origin. Parent must be an origin group:

...<origin>.buffer

Parameter	Value
type	archive
version	1.0.0
name	archive
label	Archive

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

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

Tasks

Archive Task

Mine Task

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

Origin

Definitions

Task

Mnemonic

Mnemonic Bin

Databases

Definitions

Event Definitions

Mnemonic Definitions

Nominal Def

Plot Def

Profile Def

Diagram Def

Events

Event

Fields

Changelog

1.0.1

1.0.0

Event File

Event Files

Mnemonics

Mn Full

Mn Buffer

Mn Delta

Mn Bin Time

Mn Bin Interval

Mn File Archive

Mn File Buffer

Tasks

Archive Task

Mine Task

Spectra

Spectra Tab Conf

Spectra Database Tab

Spectra Presearch Conf

Spectra Field Presearch

Spectra Filters Conf

Spectra Charts Conf

Spectra Chart Conf

Spectra Tables Conf

Spectra Query Conf

Spectra Labels Conf