Variant concepts

The "value" property is a required property that contains the value to be stored in the variant field. It is always a JSON value, which may be a JSON string, number, boolean, object, or array.

The example below shows a JSON string containing a number being stored in the variant as a big integer.

{
 "schema": "jsonaction.org/schemas/variantObject",
 "value": "1234567890123456789",
 "type": "bigint"
}

The optional "valueEncoding" property specifies how the sender encodes the "value" property so the receiver can decode it. Valid values include [], ["base64"], ["byteArray"], and ["hex]". 

In the following example, the "valueEncoding" property is an empty array because there are no additional decoding steps beyond converting from the JSON number type specified in the "value" property to the big integer number specified in the "type" property.

Using an empty array is the same as setting "valueEncoding" to null or omitting it.

{
 "schema": "jsonaction.org/schemas/variantObject",
 "value": 123,
 "valueEncoding": [],
 "type": "number",
}

The "storageEncoding" property is an optional array that specifies additional steps for optimizing the value that will be stored in a variant field, such as compressing the value or converting it to a more efficient format before writing it to the table (in order to save disk space). For example, a JSON type can be encoded as BSON before it is written to the table file. 

Each variant in each record can potentially specify a different set of encodings for the same "value". This is useful for migrating data incrementally from one encoding to another, such as incrementally converting natively stored JSON into CBOR. This is also useful for compressing data with different algorithms depending on which algorithm is more effective, such as using 7z for large strings, using RLE for small strings containing repeated characters, and using no compression for very small strings.

The steps in "storageEncoding" are specified in the order in which they encode data. They define the encoding starting after the encoding specified in the "type" property to the binary value stored in the field. 

When there are no additional steps in the "storageEncoding" property, it must be omitted, set to [], or set to null.

When storing a variant into the database, the "value" property implicitly specifies the initial data type by how its value is represented in the JSON itself (as a quoted string, number, object, list, etc). The "valueEncoding" steps, if any, define how to convert the "value" into the data type specified by the "type" property. 

A FairCom server automatically runs the "storageEncoding" steps on the data before storing it and after retrieving it. When retrieving a variant value, the database runs the "storageEncoding" steps in reverse order on the stored binary value to convert it into the field value specified by the "type" property.

The following example is a variant containing a user-defined "personV2" type that is a JSON document validated by a "personV2" JSON schema and stored in the variant field in the "CBOR" binary format in big endian byte order.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": 
  {
    "schema":"faircom.com/schemas/personV2",
    "employeeId": 17, 
    "name":"Mike Bowers"
  },
  "valueEncoding": [], 

  "type": "personV2",
  "storageEncoding": ["json","cbor"]
}

The "type" property is a required property that contains the data type of the value. It can be a string or a number. Each type has a unique name and a unique integer identifier.

The list of types are specified in the variant_type table. The numeric value of "type" must be a value in the data_type_id field. The string value of "type" must be a value in the data_type_name field.