Variant data type tutorials

Use the following tutorials to use the variant data type effectively

Variant object using a numeric `"type"`

Each type is identified by a unique number. The number 5 is the number assigned to the "integer" type. The basic variant types table shows the most common types with their names and numbers.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "123",
  "type": 5
}

The variant JSON object supports two optional properties: "valueEncoding" and "storageEncoding". The "valueEncoding" property tells the server and application how to decode the value of the "value" property. The "storageEncoding" tells the server how to encode the value when it stores the binary value in the table record and how to decode the value when it retrieves the value from the table record.

Setting the variant object with value encoding

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "eyJhIjoiYiJ9",
   "valueEncoding": ["base64"],
  "type": "json"
}

When sending the preceding variant object to the server, it tells the server that the value "eyJhIjoiYiJ9" is encoded as "base64" in the "value" property in the JSON.

Because "valueEncoding" is set to ["base64"],the server uses the base64 algorithm to decode the value "eyJhIjoiYiJ9" into a binary buffer. This puts the following UTF-8 characters in the buffer: {"a":"b"}.
Because the specified type is "json", the server validates that the binary buffer contains valid JSON.
1. The server ensures the bytes in the binary buffer are a valid UTF-8 string.
2. The server ensures the UTF-8 string represents a valid JSON document.

When receiving the preceding variant object from the server, the "valueEncoding" property tells the application that the value "eyJhIjoiYiJ9" is encoded as a "base64" string.

Setting the variant object with type encoding

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": 1234,
  "type": "json",
}
{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "FFAA01",
  "type": "binary",
  "valueEncoding": ["hex"]
}
{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "cagdeabb==",
  "type": "binary",
  "valueEncoding": ["base64"]
}
{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": {"a":"b"},
  "type": "json",
  "storageEncoding": ["bson"]
}

In the last example, the "storageEncoding" property is "bson".

Because the specified type is "json", the server validates that the value {"a":"b"} is a valid JSON document.
Because the "storageEncoding" is set to ["bson"], the server converts the JSON into BSON and stores the BSON value in the record.

Setting the variant object with value and type encodings

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "eyJhIjoiYiJ9",
  "valueEncoding": ["base64"],

  "type": "json",
  "storageEncoding": ["bson"]
}

The example above causes the server to decode the value as base64, validate that it is JSON, convert the JSON into BSON, and store the BSON in the variant field.

Because the value of "valueEncoding" and "storageEncoding" is an array, the user can specify a series of encodings.

Setting the variant object with multiple encodings in each value and type

In the following example, the "valueEncoding" property tells the server to decode the value as base64 and then unzip the binary value using the 7z algorithm into a binary buffer. The "type" property tells the server to validate the binary buffer as JSON. The "storageEncoding" property tells the server to encode the value as BSON in big endian byte order and store the result in the record.

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

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

Tip

The receiver of a variant JSON object may be an application or a FairCom server. The receiver of a variant JSON object should decode the "value" property using the steps in "valueEncoding" in order from first to last.
- The first step, if present, is the current encoding of the "value" property, such as "base64".
- The next step, if present, is an underlying encoding, such as "7z".
- When the receiver has finished decoding the "value" property, it has recreated the variant's raw binary value.

Tip

Only a FairCom server processes the "storageEncoding" property and it works differently than "valueEncoding".
- Before the server writes the variant's raw binary value to the table record, it takes the binary value and follows the steps in "valueEncoding" in order from first to last to encode the value for storage.
- When the server reads the variant's stored value from the table record, it takes the stored value and follows the steps in "valueEncoding" in reverse order from last to first to decode the value into the variant's raw binary value. Then it further encodes the value using the steps in "valueEncoding" in order from first to last.

Null variant

Storing null in a variant with the "type" set to any value, sets the variant field to null. Retrieving the variant value returns null. The field is set to NULL. This works only when the variant field is nullable. When the variant field is not nullable, setting a null value returns an error.

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

Variant containing big integer

A FairCom signed 8-byte integer can be stored in a variant. The empty "valueEncoding" indicates that a JSON number is assigned to the "value" property.

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

Variant containing big integer encoded as a JSON string

A FairCom 8-byte signed integer is stored in a variant. The "valueEncoding" of "number" indicates that a JSON string containing an embedded number is assigned to the "value" property.

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

Timestamp variant encoded as ISO 8601 string (default)

A FairCom timestamp is stored in a variant. The "valueEncoding" of "iso8601" indicates that a JSON string containing an ISO 8601 timestamp is assigned to the "value" property. The length of the variant field indicates when the timestamp includes millisecond resolution.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "1956-05-07T10:41:37.5",
  "valueEncoding": ["iso8601"],
 
  "type": "timestamp",
  "storageEncoding": []
}

Time variant encoded as JSON time object

A FairCom time with millisecond precision is stored in a variant. The "valueEncoding" of "jsonTimeObject" indicates that a JSON time object is assigned to the "value" property. The length of the variant field indicates when the time includes millisecond resolution.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": {"hour": 10, "minute": 41, "second": 37, "millisecond": 500 },
  "valueEncoding": ["jsonTimeObject"], 

  "type": "time",
  "storageEncoding": []
}

Date variant encoded as JSON date object

A FairCom date stored in a variant and returned in the JSON value as a JSON object containing a date.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": {"year": 2023, "month": 12, "day": 1 },
  "valueEncoding": ["jsonDateObject"], 

  "type": "date",
  "storageEncoding": []
}

Timestamp variant encoded as a JSON timestamp object

A FairCom timestamp with millisecond precision is stored in a variant. The "valueEncoding" of "jsonTimestampObject" indicates that a JSON timestamp object is assigned to the "value" property. The length of the variant field indicates when the timestamp includes millisecond resolution.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": { "year": 2023, "month": 12,  "day": 1, 
             "hour": 10,   "minute": 41, "second": 37, "millisecond": 500 
           },

  "valueEncoding": ["jsonTimestampObject"],
 
  "type": "timestamp",
  "storageEncoding": []
}

JSON variant stored as a BSON and returned as JSON

JSON is stored in a variant as a BSON. The empty "valueEncoding" indicates that the JSON value is assigned to the "value" property.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": {"a":"b"},
  "valueEncoding": [],
 
  "type": "json",
  "storageEncoding": ["bson"]
}

JSON variant stored as 7z and returned as JSON

JSON is stored in a variant using 7z compression. The empty "valueEncoding" indicates that the JSON value is assigned to the "value" property.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": {"a":"b"}, 
  "valueEncoding": [],

  "type": "json",
  "storageEncoding": ["7z"]
}

JSON variant stored as RLE and returned as 7z Base64 encoded as JSON

JSON document {"a":"b"} stored in a variant as a runtime-length-encoded (RLE) compressed binary and returned in the JSON "value" property as a base64 encoding of a 7z compressed binary value of the JSON document.

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

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