variantFormat

The "variantFormat" property tells the server how to interpret the variant data included in a JSON Action request. This property is an optional string that defaults to "json".

The "variantFormat" property has one of the following values: "binary", "json", "string", and "variantObject". It tells the server how to store and return values stored in variant fields. 

The server applies the "variantFormat" property to all variant fields affected by a JSON action, such as all variant fields inserted by the "insertRecord" action or all variant fields returned by the "getRecordsByIndex" action. If you want more control, set the "variantFormat" property to "variantObject" and you can use variant objects to independently set the variant type and encoding of each variant field in a JSON action.

A variant field is a flexible, strongly-typed field. It is flexible because each variant field in each record can store any type of data. It is strongly typed because each variant field in each record stores the type of value it contains.

A variant field's type can currently be set to "binary", "json", "string", and "boolean" values. In the future, you will be able to set it to other values, such as "jpeg", "xml", and user-defined types.

The following sections describe each value of the "variantFormat" property.

 

"variantFormat": "binary"

  • Use the "variantFormat": "binary" setting to store and return variant field values as binary values embedded in JSON strings.
  • The "binary" variant type ensures maximum compatibility and performance across all FairCom APIs, including JSON DB, SQL, CTDB, and ISAM.
  • When "variantFormat" is "binary", the server sets the variant's type to "binary" and stores raw bytes in the variant field.
  • The binary value can be any sequence of bytes.
  • The server does not validate the binary value.
  • The "binaryFormat" property specifies how the client and server format binary value. For example, the "hex" value embeds hexadecimal numbers in a JSON string.

 

"variantFormat": "json"

  • Use the "variantFormat": "json" setting to store and return variant field values as JSON values.
  • The "json" variant type provides maximum convenience in FairCom's JSON APIs.
  • The server validates JSON before it assigns it to a variant field.
  • The server converts a variant field to valid JSON before it returns the value of a variant field.
    • The "binaryFormat" property specifies the format of a binary variant value embedded in a JSON string.
    • The "numberFormat" property causes the server to return numbers as JSON numbers or JSON strings containing embedded numbers. All languages and JSON parsers work well with strings containing embedded numbers – even extremely large and small numbers.
  • When "variantFormat" is "json", the server sets the variant's type to "json" and stores a JSON value in the variant field.
    • The server does not store a JSON null; instead it marks the variant field as NULL. If the field is not nullable, the API returns an error.
    • The server stores a JSON string in the variant field as is. It includes the double quotes before and after the string's value and stores escaped characters without decoding them. For example, the server stores the JSON string, "my // string",  as "my // string". The server returns a JSON string exactly as it stores it.
    • The server stores a JSON number in the variant field as is. A number consists of the following ASCII characters 1234567890+-.eE. For example, the server stores the JSON number -123.45 as the ASCII characters -123.45. The server returns a JSON string exactly as it stores it.
    • The server stores a JSON true and false in the variant field as is. It stores and returns the ASCII characters true or false.
    • The server stores a JSON object and array as is. When it validates the JSON, it minimizes whitespace while preserving the ASCII characters representing the actual object or array. For example, the server stores the array [1,2,3]  as the ASCII characters [1,2,3].

 

"variantFormat": "variantObject"

  • Use the "variantFormat": "variantObject" setting to store and return variant field values as a variant object.
  • The variant object defines everything the server and client need to know about a variant, including its type, value, value encoding, and storage encoding.
  • The "variantObject" variant type provides maximum flexibility across all FairCom APIs and programming languages.
  • A variant object is a JSON object containing the following properties: "schema", "value", "valueEncoding", and "type". The "schema" property must have the value "jsonaction.org/schemas/variantObject".
  • When "variantFormat" is "variantObject", the server parses the variant object and uses its properties to determine how to store the variant value.
    • The "value" property contains the variant field's value .
    • The "valueEncoding" property specifies how the value is encoded so the server and client can decode the value. For example, assigning "hex" to "valueEncoding" indicates the "value" property contains a binary value embedded in a string as hexadecimal characters. The server decodes the value before storing it in the variant field. In FairCom's JSON APIs, the "binaryFormat" property in the "responseOptions" object specifies how the server encodes the binary value before returning it.
    • The "type" property specifies the variant's type, such as "json", "binary", and "string". In the future, the FairCom server will support additional types, such as "jpeg", "xml", and user-defined types.
  • When the "insertRecords" and "updateRecords" actions have "variantFormat": "variantObject" in "params", you must assign a variant object to each variant field.
  • A JSON action returns a variant object for a variant field value when you put "variantFormat": "variantObject" in "responseOptions".

 

Variant object examples

 

Binary value in a variant object

Add "binaryFormat": "base64" to "responseOptions" to tell the server to encode the variant value as Base64.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "ewogICJrZXkiOiAidmFsdWUiCn0=",
  "valueEncoding": ["base64"],
  "type": "binary"
}

 

Number in a variant object

Add "numberFormat": "string" to "responseOptions" to tell the server to embed the number in a string.

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

 

Add "numberFormat": "number" to "responseOptions" to tell the server to encode the number as a JSON number.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": 123.45,
  "type": "number"
}

 

Boolean in a variant object

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": true,
  "type": "boolean"
}

 

String in a variant object

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "A JSON string with embedded \" double quote.",
  "type": "string"
}

 

JSON in a variant object

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": [1,"2",{"key": "value"}],
  "type": "json"
}

Was this article helpful?

Give feedback about this article

Related Articles