Variant type
The variant data type can store any value. It specifies the data type so the database and application can easily use the data. The FairCom server comes with predefined data types, and in a future release, you will be able to create your own.
A variant field in a table is flexible because it can store any type of value. It is strongly typed because it stores the type and value of the data it contains. Each record containing a variant field may store a different type of value. For example, one record might store a JSON document, another record might store a GIF image, and another might store a raw binary value.
The variant data type uses a JSON object to represent any value. This JSON object is called the variant object. You can use a variant object in a JSON document. Any system can read the variant object and be programmed to convert it into a native binary value.
The variant object brings strongly typed values to JSON. It enables you to embed binary values in JSON and specify the data type and encoding of those values, such as images, PDFs, and binary formats like BSON and CBOR.
Variant Object
A variant object is a JSON object that describes all aspects of the data stored in a variant field, including its value, its type, and how the value is encoded. It is a standard way of representing any type of data. It is built into all FairCom products. People can easily read it, and computer languages can use it to transmit strongly typed binary data between applications.
In FairCom JSON APIs, you can use the variant object to insert or update data in a variant field. The APIs detect the presence of a variant object when a JSON object contains the "schema" property set to "jsonaction.org/schemas/variantObject". The following variant object represents a GIF image. It stores the image in the "value" property as a string containing Base64 encoded characters.
{
"schema": "jsonaction.org/schemas/variantObject",
"value": "R0lGODlhAQABAIAAAAAAAP///yH5BAUAAAEALAAAAAABAAEAAAICRAEAOw==",
"valueEncoding": ["base64"],
"type": "gif",
}The following sections contain examples of variant objects. They show you how to use a variant object to represent all major data types.
When the variant object's "type" property is "json", you can assign any JSON value directly to the "value" property. The server stores the value as JSON inside the variant field. You do not need to specify the "valueEncoding" property for the server to interpret the value properly.
JSON string in a Variant Object
{
"schema": "jsonaction.org/schemas/variantObject",
"value": "my string",
"type": "json"
}JSON number in a Variant Object
{
"schema": "jsonaction.org/schemas/variantObject",
"value": -123.456,
"type": "json"
}JSON boolean in a Variant Object
{
"schema": "jsonaction.org/schemas/variantObject",
"value": false,
"type": "json"
}JSON null in a Variant Object
{
"schema": "jsonaction.org/schemas/variantObject",
"value": null,
"type": "json"
}
JSON object in a Variant Object
{
"schema": "jsonaction.org/schemas/variantObject",
"value": { "myKey": "myValue"},
"type": "json"
}JSON array in a Variant Object
{
"schema": "jsonaction.org/schemas/variantObject",
"value": [1, "2", 3.0],
"type": "json"
}When you want to store a binary value in a variant field, set the "type" property to "binary", set the "valueEncoding" property to "base64", "hex", or "byteArray", and set the "value" property to a binary value embedded in a string or array.
Binary data embedded in a string in hexadecimal format
{
"schema": "jsonaction.org/schemas/variantObject",
"value": "00FF1E58",
"valueEncoding": "hex",
"type": "binary"
}Binary data embedded in a string in Base64 format
{
"schema": "jsonaction.org/schemas/variantObject",
"value": "AP8eWA==",
"valueEncoding": "base64",
"type": "binary"
}Binary data as an array of bytes
{
"schema": "jsonaction.org/schemas/variantObject",
"value": [0, 255, 30, 88],
"valueEncoding": "byteArray",
"type": "binary"
}When you want to store a number in a variant field, set the "type" property to "number", omit the "valueEncoding" property, and set the "value" property to a JSON number or string containing a number.
Example of a numeric Variant object
{
"schema": "jsonaction.org/schemas/variantObject",
"value": -123.456,
"type": "number"
}Embedding a number in a string
When the "type" property is "number", you can embed a number in a string, and the FairCom server will properly convert and store it in a variant field as a number.
It is common to store numbers in a string because JSON numbers are decimal numbers with no limits on the number of digits to the left and right of the decimal point. JSON parsers and many programming languages cannot handle numbers with more than 15 digits of precision. For example, most languages and JSON parsers convert JSON numbers into IEEE floating point numbers, which are lossy numbers. They may change a number's value when converting between JSON's base ten value and the IEEE number's binary value. They will change a number's value when it has more than 15 digits of precision.
To prevent such problems, you must embed a number inside a JSON string. To do this in a Variant Object, set the "type" property to "number", omit the "valueEncoding" property, and set the "value" property to a string containing a number.
Example of a numeric Variant object using a JSON string to represent a number
{
"schema": "jsonaction.org/schemas/variantObject",
"value": "-123.456",
"type": "number"
}
To store a string in a Variant Object, set the "type" property to "string" and assign a string to the "value" property. Omit the "valueEncoding" property.
Example of a Variant object representing a number embedded in a string
{
"schema": "jsonaction.org/schemas/variantObject",
"value": "my string",
"type": "string"
}To store a Boolean value in a Variant Object, set the "type" property to "boolean" and assign true or false to the "value" property. Omit the "valueEncoding" property.
Example of a Variant object representing a number embedded in a string
{
"schema": "jsonaction.org/schemas/variantObject",
"value": true,
"type": "boolean"
}JSON Action APIs
FairCom's JSON action APIs read and write to variant fields. By default, they read and write JSON to variant fields. They can also use variant objects and settings to read and write binary values to variant fields.
CTDB and ISAM
CTDB and ISAM APIs read and write to a variant field using a C structure representing the variant object, including its length, value, type, and storage encoding.
SQL
SQL reads and writes to a variant field using its binary value. In the future, you can set and return its value using the Variant Object.