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 |
Category
Mid-level struct group for organization. Must be child of project or category.
Created with the STRUCT CREATE CATEGORY
action.
Group Parameters
Parameter | Value |
---|---|
name | * |
label | * |
Struct Parameters
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(8) |
✓ | 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 toenums
since "enum" is often a reserved keyword -
meas
field removed (measure now assumed fromunit
)
Mnemonic Tracking
Used for tracking mnemonic selection activity. Though this is not technically a definition database, it is used alongside the mnemonic definitions database, and is thus defined in the def context.
Database Parameters
Parameter | Value |
---|---|
name | mn_track |
label | Mnemonic Tracking |
format | "{t} {user} {mn_id}" |
order | (name , asc) |
singular | "mnemonic definition" |
Struct Parameters
Parameter | Value |
---|---|
type | def_mn_track |
v | 1.0.0 |
Fields
Name | Type | Req | Description |
---|---|---|---|
t | instant(us) |
✓ | time of selection |
mn_id | int(4) |
✓ | mnemonic ID selected |
user | user_id |
✓ | user taking action |
mn_ids | set(int(4)) |
other mnemonic ID(s) selected | |
models | set(asciistring) |
model(s) in current context |
Changelog
1.0.1 (planned)
- order changed to (
t
, desc) - format changed to
"{t} {mn_id} {user}"
Nominal Definitions
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 nominal range description | |
color | struct_nominal_color |
additional arbitrary metadata | |
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
1.1.0 (planned)
-
label
changed toname
for consistency with other structs databases
Plot Configuration Definitions
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 ) |
Changelog
1.1.0 (planned)
-
conf
changed fromjsonobject
tostruct_plot_conf
Profile Definitions
Holds mnemonic profile definitions.
Database Parameters
Parameter | Value |
---|---|
name | profile |
label | Profile |
format | "{name}" |
order | [name , asc] |
singular | "profile" |
Struct Parameters
Parameter | Value |
---|---|
type | def_profile |
v | 1.0.0 |
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
1.1.0 (planned)
- TBD
Diagram Definitions
Holds diagram definitions. The diagram itself is in an attached SVG file.
Database Parameters
Parameter | Value |
---|---|
name | diagram |
label | Diagram |
format | "{name}" |
order | (name , desc) |
singular | "diagram" |
Struct Parameters
Parameter | Value |
---|---|
type | def_diagram |
v | 1.0.0 |
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
1.1.0 (planned)
- order changed to (
name
, asc) - added
desc
field
Event Databases
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.
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" ) |
Struct Parameters
Parameter | Value |
---|---|
type | event |
v | 1.0.2 |
Fields
Name | Type | Req | Virtual | 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) |
✓ | ✓ | 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) |
|
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 |
Notes
Virtual fields are calculated from other fields and cannot be populated manually.
Changelog
1.0.2
- corrected
t_end
anddur
as not required
1.0.1
- corrected
name
as not required
1.0.0
-
pid
(primary ID) changed toe_id
(event ID) to avoid confusion -
sid
removed (additional IDs may be added as needed) -
int
changed tointerval
(int
is commonly reserved keyword) -
dur
,interval
, andopen
are now derived fields fromt_start
andt_end
- added
struct_event_type
andstruct_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" ) |
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.