Variant objects

Concepts about representing the variant data type as a variant object

Variant Objects

A variant object is a JSON object that functions as a standard representation of any type of value because it contains key information including its value, type, value encoding, and storage encoding. Any application can use it to exchange data reliably. FairCom uses it in its JSON API to represent data types that JSON does not support, such as binary data. It has up to five properties: "schema", "value", "type", "valueEncoding", and "storageEncoding". 

The variant object requires the "schema", "value", and "type" properties. 

  • The value of the "schema" property is always set to "jsonaction.org/schemas/variantObject", which uniquely identifies a JSON object as a variant object. 
  • When sending a variant object to the server, the server converts the value in the "value" property to the type specified in the "type" property and stores the converted value. 
  • When receiving a variant object from the server, the "type" property tells the application the type of the variant value. This is important because JSON cannot represent many types of values, including binary values, images, dates, etc. For example, the "value" property may be assigned to a string and inside the string may be Base64 value representing a PNG image.

 

Example variant object

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

 

Variant object properties

Property Description Default Type Limits (inclusive)

value

The "value" property contains the value to be stored in the variant field.

When the type is "json", the "value" property can be assigned to any valid JSON value, including a JSON string, number, object, array, true, false, or null.

This example shows a JSON object being assigned to the "value" property .

{ 
  "schema": "jsonaction.org/schemas/variantObject", 
  "value": { "myKey": "myValue"}, 
  "type": "json" 
}
 Required - No default value JSON value

"string"

"number"

"boolean"

"object"

"array"

type

The "type" property specifies the data type of the "value" property.

Each type has a unique name. See List of Variant Types for the complete list.

The following example is a variant object containing a PNG image encoded as Base64.

{
 "schema": "jsonaction.org/schemas/variantObject",
 "value": "77+9UE5HChoKAAAACklIRFIAAAABAAAAAQgCAAAA77+9d1Pvv70AAAAMSURBVHjvv71jYGBgAAAABAAB77+9FzhVAAAAAElFTkTvv71CYO+/vQ==",
  "type": "png",
  "valueEncoding": "base64"
}

 

 Required - No default value enum

Fundamental types

"string"

"binary"

"number"

"boolean"

"json"

 

Document types

"xml"

"html"

"markdown"

"rtf"

 

Code types

"javascript"

"css"

"sql"

 

Data types

"csv"

"tsv"

"turtle"

"vcard"

 

Image types

"bmp"

"gif"

"jpeg"

"png"

"svg"

 

Video types

"mp4"

"quicktime"

"mpeg"

"png"

"svg"

 

Audio types

"flac"

"opus"

 

Music types

"midi"

"spMidi"

 

Font types

"otf"

valueEncoding

The "valueEncoding" property specifies how the sender encodes the "value" property so the receiver can decode it. Any binary value can be and represented in a variant object encoded as hexadecimal, Base64, or an array of bytes. Assigning an empty array to "valueEncoding" is the same as setting it to null or omitting it.

The following example encodes the text Hi! as hexadecimal so it can be stored as a binary value. 

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "486921",
  "type": "binary",
  "valueEncoding": "hex"
}
 Optional with default of [] array

[]

["base64"]

["byteArray"]

["hex"]

storageEncoding

The "storageEncoding" property specifies how the value should be physically stored in a database by specifying additional steps for optimizing the value that will be stored in a variant field, such as converting it to a more efficient format before writing it to the table (in order to save disk space). Assigning an empty array to "storageEncoding" is the same as setting it to null or omitting it. 

The following example encodes the text Hi! as hexadecimal so it can be stored as a binary value. 

["bigint"]
 Optional with default of [] array ["tinyint"]
["smallint"]
["integer"]
["bigint"]
["float"]
["double"]
["numeric"]

 

alternative ideas different perspectives

Was this article helpful?

Give feedback about this article

Related Articles