This document describes the serialization to JSON of vTypes as provided by this library. The purpose of the JSON serialization is to interoperate with different domains, such as web services/sockets and python scripting.
Current support is included for the following types:
Note that JSON serialization in verbose and not efficient. Therefore it can be used for data of moderate size and slow update rate. Hopefully, in the future, BSON will reach a standardization point and availability, to handle more efficient encoding.
The JSON serialization is broken down into the basic vTypes components:
The serialization of each element is common across vTypes.
The purpose of the type field is to signal that a particular JSON object is the serialization of a vType. It will also contain all information needed to de-serialize or use the object, including the version and actual type name.
Type definition:
type :=
String name
String version
The type name can be one of supported types:
Scalars Arrays Complex
VDouble VDoubleArray VTable
VFloat VFloatArray
VLong VLongArray
VInt VIntArray
VShort VShortArray
VByte VByteArray
VBoolean VBooleanArray
VEnum VEnumArray
VString VStringArray
This document refers to version "1"
An example of a JSON instance of Type:
{
"name": "VDouble",
"version": "1"
}
An Alarm:
Alarm :=
String severity
String status
Descriptions:
Alarm:
Alarm information. Represents the severity and name of the highest alarm
associated with the channel.
severity:
Severity that MUST be a value in the enumeration:
[NONE, MINOR, MAJOR, INVALID, UNDEFINED].
status:
Status is a short string that represents the alarm.
Example of a JSON fields for an Alarm:
{
"severity": "NONE",
"status": "NONE",
}
{
"severity": "MINOR",
"status": "LOW",
}
A Display:
Display :=
Number lowAlarm
Number highAlarm
Number lowDisplay
Number highDisplay
Number lowWarning
Number highWarning
String units
Descriptions:
Display:
Limit and unit information needed for display.
The numeric limits are given in double precision no matter which numeric
type. The unit is a simple String, which can be empty if no unit
information is provided.
lowAlarm:
Lowest value of the alarm range.
highAlarm:
Highest value of the alarm range.
lowDisplay:
Lowest value of the display range.
highDisplay:
Highest value of the display range.
lowWarning:
Lowest value of the warning range.
highWarning:
Highest value of the warning range.
units:
Text representation of the units used for values.
An example of a JSON instance of a Display:
{
"lowAlarm": -80,
"highAlarm": 80,
"lowDisplay": -100,
"highDisplay": 100,
"lowWarning": 75,
"highWarning": 75,
"units": "m"
}
An Enum:
Enum :=
String[] labels
Descriptions:
Enum:
The metadata necessary to encode an enumeration.
labels:
All the possible labels.
MUST contain at least one element.
MUST contain unique elements.
An example of a JSON instance of an Enum
{
"labels": [
"ON",
"OFF",
"DISABLED"
]
}
A Time:
Time :=
Integer unixSec
Integer nanoSec
Integer userTag
Descriptions:
Time:
Time information.
unixSec:
Unix seconds portion of the timestamp. 64-bit signed.
nanoSec:
Nano seconds portion of the timestamp. 32-bit signed with a valid
range of 0-999,999,999.
userTag:
A user defined tag, that can be used to store extra time information,
such as beam shot.
An example of a JSON instance of a Time:
{
"unixSec": 1354719441,
"nanoSec": 521786982,
"userTag": 1
}
A scalar numeric value:
VNumber :=
Type type
Number value
Alarm alarm
Time time
Display display
The type/name can be one of VDouble/VFloat/VLong/VInt/VShort/VByte. The value is always a JSON number, but the type/name will define the range allowed to such value.
Descriptions:
VNumber:
Basic type definition for all scalar numeric types, containing a value and
metadata. One must always look at the alarm severity to be able to
correctly interpret the value.
value:
The numeric value.
alarm:
Alarm linked with the value.
time:
Time linked with the value.
display:
Display linked with the value.
An example of a JSON instance of a VDouble:
{
"type" : {
"name": "VDouble",
"version": "1"
}
"value": 3.1415,
"alarm": {
"severity": "NONE",
"status": "NONE",
},
"time": {
"unixSec": 1354719441,
"nanoSec": 521786982,
"userTag": 0
}
"display": {
"lowAlarm": -80,
"highAlarm": 80,
"lowDisplay": -100,
"highDisplay": 100,
"lowWarning": 75,
"highWarning": 75,
"units": "rad"
},
}
A scalar boolean value:
VBoolean :=
Type type
Boolean value
Alarm alarm
Time time
The type/name MUST be VBoolean. The value MUST the JSON constant TRUE or FALSE.
Descriptions:
VBoolean:
Basic type definition for scalar boolean, containing a value and
metadata. One must always look at the alarm severity to be able to
correctly interpret the value.
value:
The boolean value.
alarm:
Alarm linked with the value.
time:
Time linked with the value.
display:
Display linked with the value.
An example of a JSON instance of a VBoolean:
{
"type" : {
"name": "VBoolean",
"version": "1"
}
"value": true,
"alarm": {
"severity": "NONE",
"status": "NONE",
},
"time": {
"unixSec": 1354719441,
"nanoSec": 521786982,
"userTag": 0
}
}
A scalar enumeration value:
VEnum :=
Type type
Integer value
Alarm alarm
Time time
Enum enum
The type/name MUST be VEnum. The value MUST be an integer in the range given by enum/labels.
Descriptions:
VEnum:
Basic type definition for scalar enum, containing a value and
metadata. One must always look at the alarm severity to be able to
correctly interpret the value.
value:
The index of the value in the enum/labels array.
alarm:
Alarm linked with the value.
time:
Time linked with the value.
enum:
Enum linked with the value.
An example of a JSON instance of a VEnum:
{
"type" : {
"name": "VEnum",
"version": "1"
}
"value": 1,
"alarm": {
"severity": "NONE",
"status": "NONE",
},
"time": {
"unixSec": 1354719441,
"nanoSec": 521786982,
"userTag": 0
}
"enum": {
"labels": [
"ON",
"OFF",
"DISABLED"
]
}
}
A scalar string value:
VString :=
Type type
String value
Alarm alarm
Time time
The type/name MUST be VString. The value MUST be a JSON string.
Descriptions:
VString:
Basic type definition for scalar string, containing a value and
metadata. One must always look at the alarm severity to be able to
correctly interpret the value.
value:
The string value.
alarm:
Alarm linked with the value.
time:
Time linked with the value.
An example of a JSON instance of a VString:
{
"type" : {
"name": "VString",
"version": "1"
}
"value": "Hello",
"alarm": {
"severity": "NONE",
"status": "NONE",
},
"time": {
"unixSec": 1354719441,
"nanoSec": 521786982,
"userTag": 0
}
}
A numeric array value:
VNumberArray :=
Type type
Number[] value
Alarm alarm
Time time
Display display
The type/name MUST be one of VDoubleArray/VFloatArray/VLongArray/VIntArray/VShortArray/VByteArray. The value is always a JSON number array, but the type/name will define the range allowed to such value.
Descriptions:
VNumberArray:
Type definition for all numeric array types, containing a value and
metadata. One must always look at the alarm severity to be able to
correctly interpret the value.
value:
The numeric array.
alarm:
Alarm linked with the value.
time:
Time linked with the value.
display:
Display linked with the value.
An example of a JSON instance of a VDoubleArray:
{
"type" : {
"name": "VDoubleArray",
"version": "1"
}
"value": [
0.0,
0.1,
0.2
],
"alarm": {
"severity": "NONE",
"status": "NONE",
},
"time": {
"unixSec": 1354719441,
"nanoSec": 521786982,
"userTag": 0
}
"display": {
"lowAlarm": -80,
"highAlarm": 80,
"lowDisplay": -100,
"highDisplay": 100,
"lowWarning": 75,
"highWarning": 75,
"units": "m"
},
}
A boolean array value:
VBooleanArray :=
Type type
Boolean[] value
Alarm alarm
Time time
The type/name MUST be VBooleanArray. The value MUST be an array that contains only the JSON constants TRUE or FALSE.
Descriptions:
VBooleanArray:
Type definition for boolean array, containing a value and
metadata. One must always look at the alarm severity to be able to
correctly interpret the value.
value:
The boolean array.
alarm:
Alarm linked with the value.
time:
Time linked with the value.
display:
Display linked with the value.
An example of a JSON instance of a VBoolean:
{
"type" : {
"name": "VBoolean",
"version": "1"
}
"value": [
true,
false,
true
]
"alarm": {
"severity": "NONE",
"status": "NONE",
},
"time": {
"unixSec": 1354719441,
"nanoSec": 521786982,
"userTag": 0
}
}
A enumeration array value:
VEnumArray :=
Type type
Integer[] value
Alarm alarm
Time time
Enum enum
The type/name MUST be VEnumArray. The value MUST be an array of integers in the range given by enum/labels.
Descriptions:
VEnumArray:
Type definition for enum array, containing a value and
metadata. One must always look at the alarm severity to be able to
correctly interpret the value.
value:
The array of indexes of the values in the enum/labels array.
alarm:
Alarm linked with the value.
time:
Time linked with the value.
enum:
Enum linked with the value.
An example of a JSON instance of a VEnumArray:
{
"type" : {
"name": "VEnumArray",
"version": "1"
}
"value": [
1,
0,
1
]
"alarm": {
"severity": "NONE",
"status": "NONE",
},
"time": {
"unixSec": 1354719441,
"nanoSec": 521786982,
"userTag": 0
}
"enum": {
"labels": [
"ON",
"OFF",
"DISABLED"
]
}
}
A string array value:
VStringArray :=
Type type
String[] value
Alarm alarm
Time time
The type/name MUST be VStringArray. The value MUST be a JSON string array.
Descriptions:
VStringArray:
Type definition for scalar string, containing a value and
metadata. One must always look at the alarm severity to be able to
correctly interpret the value.
value:
The string array value.
alarm:
Alarm linked with the value.
time:
Time linked with the value.
An example of a JSON instance of a VStringArray:
{
"type" : {
"name": "VString",
"version": "1"
}
"value": [
"A",
"B",
"C"
]
"alarm": {
"severity": "NONE",
"status": "NONE",
},
"time": {
"unixSec": 1354719441,
"nanoSec": 521786982,
"userTag": 0
}
}
A table:
VTable :=
Type type
String[] columnNames
String[] columnTypes
Object[][] columnValues
Descriptions:
Table:
A table. Tables are collections of columns, each of which is composed of
a column name, type, and data array. All elements of the same
column MUST be of the same type.
Unit information is contained within the ScalarArray columns Display
field.
columnNames:
A string array with the names of the columns.
columnTypes:
A string array with the type of each column. MUST be the same
size of columnNames. The type MUST be one of the following: String,
double, float, long, integer, short, byte.
columnValues:
An array where each element is an array with the data of each column.
The data MUST match the type. The data for a String column MUST
contain only JSON strings. The data of a double/float/long/integer/short/byte
column must contain only JSON numbers within the range and precision.
An example of a JSON instance of a VTable:
{
"type": {
"name": "VTable",
"version": 1
},
"columnNames": [
"Name",
"Index",
"Value"
],
"columnTypes": [
"String",
"int",
"double"
],
"columnValues": [
["A", "B", "C"],
[1, 2, 3],
[3.14, 1.25, -0.1]
]
}
Useful Links: