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 "valueEncoding" property specifies how the "value" property is encoded.

The "valueEncoding" property specifies how the sender encodes the "value" property so the receiver can decode it. For example, when an application calls the "insertRecords" and "updateRecords" actions to insert or update a large variant value, the application might compress the value to save network bandwidth. The application can zip and Base64-encode the value before putting it into the "value" property.  The application can set the "valueEncoding" property to ["base64", "zip"] to tell the FairCom server that the data is Base64-encoded and zipped, so it can decode it using Base64 and unzip to recreate the variant's binary value. Conversely, when an application requests a variant value from the server, it can use "valueEncoding": ["base64", "zip"] to request that the server zip and Base64-encode the value before sending it.  

The "valueEncoding" property is optional. It specifies how the sender encoded the variant value before storing it in the "value" property. It may contain zero or more steps. Each step is specified in the order needed by the receiver to convert the "value" property to the variant's binary value. The type of the variant's binary value is specified by the  "type" property.

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

When an application wants to use the "insertRecords" and "updateRecords" actions to send a variant value to a FairCom server, it may take the the variant's value and encode it zero or more times before writing the final encoded value to the variant's "value" property. The application must also add each encoding step to the "valueEncoding" list in the order the server needs to decode the "value"  property. 

Conversely, when the server returns a record to an application containing a variant field. The application reads the variant object's "value" property and must decode the value following the steps defined in the "valueEncoding" property in order from first to last.

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.

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

In the following example, the "valueEncoding" property is "number" because the "value" property is a JSON string containing an embedded number. The receiver of the variant object must decode the JSON string into the big integer number specified in the "type" property.

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

In the following example, two additional steps are added to convert from the UTF-8 string in the "value" property to the JSON type in the "type" property. These steps include using base64 to decode the value string into a binary value and using the 7z algorithm to uncompress the binary value and validating the result as JSON. Because the "storageEncoding" property defines another encoding step, the database converts the JSON into BSON and stores the BSON into the variant as the field's binary value.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "N3q8ryccAAQEJgwBDQAAAAAAAABiAAAAAAAAAHW+XQoBAAh7ImEiOiJiIn0AAQQGAAEJDQAHCwEAASEhAQAMCQAICgGcXPZrAAAFARkMAAAAAAAAAAAAAAAAERsAagBzAG8AbgBfAGEAYgAuAGoAcwBvAG4AAAAZABQKAQAwhdlCD57ZARUGAQCAAAAAAAA=", 

  "valueEncoding": ["base64", "7z"],
  "type": "json",
  "storageEncoding": ["bson"]
}

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.