`"alterSession"` (JSON Action)

Alter the settings of a session

The "alterSession" action alters the settings of the session identified by the "authToken" property. It can modify most session settings but cannot modify the "username" nor the "password" properties used to create the session. It cannot turn a temporary session into a permanent session.

The "result" property returned by the server describes the new state of the session that you just changed using the "alterSession" action.

Links: Concepts | Tutorials | FAQs

Request examples

Change timeouts

{
  "api": "admin",
  "action": "alterSession",
  "params": {
    "idleConnectionTimeoutSeconds": 60000,
    "idleCursorTimeoutSeconds": 60000
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Change many defaults simultaneously

{
  "api": "admin",
  "action": "alterSession",
  "params": {
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex",
    "defaultDebug": "max",
    "defaultResponseOptions": {
      "dataFormat": "objects",
      "numberFormat": "string",
      "binaryFormat": "hex"
    },
    "idleConnectionTimeoutSeconds": 60000,
    "idleCursorTimeoutSeconds": 60000
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "requestId": "2",
  "api": "admin",
  "action": "alterSession",
  "params": {
    "description": "new description",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex",
    "defaultVariantFormat": "binary",
    "defaultResponseOptions": {
      "dataFormat": "objects",
      "numberFormat": "string",
      "binaryFormat": "hex",
      "variantFormat": "variantObject"
    },
    "idleConnectionTimeoutSeconds": 60000,
    "permanentSession": "true",
    "idleCursorTimeoutSeconds": 60000
  },
  "responseOptions": {
    "dataFormat": "objects",
    "numberFormat": "string",
    "binaryFormat": "hex",
    "variantFormat": "json"
  },
  "apiVersion": "1.0",
  "debug": "max"
}

Response examples

Success

{
  "result": {
    "username": "ADMIN",
    "description": "My test session",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex",
    "defaultVariantFormat": "json",
    "defaultResponseOptions": {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number",
      "variantFormat": "json"
    },
    "idleConnectionTimeoutSeconds": 60000,
    "idleCursorTimeoutSeconds": 60000,
    "defaultApi": "mq",
    "defaultDebug": "max",
    "sessionStartTimestamp": "2023-04-20T18:08:56",
    "sessionLastAccessedTimestamp": "2023-04-20T18:10:22",
    "authToken": "replaceWithAuthTokenFromCreateSession"
  },
  "requestId": "00000006",
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Invalid session `"id"`/`"authToken"` failure

{
  "authToken": "invalidAuthtoken",
  "requestId": "00000011",
  "debugInfo": {
    "request": {
      "authToken": "invalidAuthtoken",
      "api": "admin",
      "action": "alterSession",
      "params": {
        "idleConnectionTimeoutSeconds": 60000,
        "idleCursorTimeoutSeconds": 60000
      },
      "requestId": "00000011"
    }
  },
  "errorCode": 12031,
  "errorMessage": "'authToken' does not match any existing session. Use a valid 'authToken' or use 'createSession' to create a valid 'authToken'."
}

The "alterSession" action modifies the settings of an existing session identified by its "authToken". While it can change most session settings, it cannot modify the "username" or "password" used to create the session, nor can it convert a temporary session into a permanent one. The server returns a "result" property describing the session's new state after the changes.

API actionsJSON ADMIN APIadmin session actionalter sessionJSON ActionalterSessionaltersSessionalterSessionssession settingspermanent sessionchange sessionupdate sessionupdate session settingsmanage session settingssession management

`"params"`

The "params" property is an object that contains an action's request parameters as defined by a set of properties. Each action defines its own required and optional properties. See System limits for a comprehensive overview of property requirements and limitations.

Table 1. alterSession "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

defaultApi

(optional) specifies the default value of the "api" property when "api" is omitted from an action request.

FairCom DB defaults to "db"

FairCom Edge defaults "hub"

FairCom MQ defaults "mq"

string enum

"admin"

"hub"

"mq"

"db"

defaultBinaryFormat

(optional) specifies the default value for the "binaryFormat" property, which tells the server how to parse binary data from the client when the binary format is not specified in the action request.

"hex"

string

One of the following: "base64", "hex", or "byteArray".

defaultDatabaseName

(optional) specifies the default value of the "databaseName" property.

FairCom DB defaults to "ctreeSQL"

FairCom Edge defaults to "faircom"

FairCom MQ defaults to "faircom"

string

1 to 64 bytes

defaultDebug

(optional) specifies the default value of the "debug" property for all requests in a session.

"max"

string enum

"none"

"max"

defaultOwnerName

(optional) specifies the initial value of the "defaultOwnerName" property used by JSON APIs and FairCom's web application.

"admin"

string

1 to 64 bytes

defaultVariantFormat

(optional) specifies the variant format the server uses when the user omits the "variantFormat" property in a JSON action request.

"json"

string

"json"

"binary"

"string"

"variantObject"

defaultResponseOptions

(optional) specifies a default value for "responseOptions" that is used by default in all other action calls. "includeFields" and "excludeFields" are mutually exclusive and "includePaths" and "excludePaths" are mutually exclusive.

{}

object

Zero or more of the following properties:

"binaryFormat"

"dataFormat"

"numberFormat"

defaultResponseOptions

.binaryFormat

(optional) specifies how binary values are returned.

"hex"

string

One of the following: "base64", "hex", or "byteArray".

defaultResponseOptions

.dataFormat

(optional) specifies what format the results will be returned in.

"arrays"

string

"default"

"arrays"

"objects"

defaultResponseOptions

.numberFormat

(optional) specifies how numbers are formatted in the JSON response message.

"number"

string

"number"

"string"

defaultResponseOptions

.variantFormat

(optional) tells the server how to interpret the variant-type data included in the request.

"json"

string

"json"

"binary"

"string"

"variantObject"

defaultRetentionPeriod

(optional) specifies how many retention units will be retained if the "retentionPeriod" property is omitted.

4

integer

1 to 100

defaultRetentionPolicy

(optional) specifies the default way in which messages are persisted if the "retentionPolicy" property is omitted.

"autoPurge"

string enum

"doNotPersist"

"neverPurge"

"autoPurge"

defaultRetentionUnit

(optional) specifies the default unit of time after which the expired messages will be purged if the "retentionUnit" property is omitted.

"week"

string enum

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

description

(optional) describes an object for later identification.

""

string

0 to 65,500 bytes

idleConnectionTimeoutSeconds

(optional) specifies the number of seconds that a session with no activity will stay open.

3600

integer

0 to 2147483647

idleCursorTimeoutSeconds

(optional) specifies the number of seconds to keep a cursor open.

600

integer

0 to 2147483647

transformBufferInitialBytes

(optional) specifies the number of bytes for the session to allocate initially for its transform buffer.

0

integer

0 or more bytes

`"defaultAPI"`

The "defaultApi" property specifies the default value of the "api" property when it is omitted from an action request. The default value for "defaultApi" is "admin", which is the API used by all session actions.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

`"defaultBinaryFormat"`

The "binaryFormat" property designates the formatof binary values embedded in JSON strings. The default value for "binaryFormat" is the "defaultBinaryFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultBinaryFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "hex". Prior to version 13.0.4, the server defaulted it to "base64".

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , "result", and "mapOfPropertiesToFields".
- It occurs in "params" when actions create or change values.
- It occurs in "responseOptions" when actions return values.
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields" transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

Our examples insert only 3 bytes into "bin". Because the "bin" field has a fixed length of 5 bytes, the server pads unused bytes with 0x00 and stores the result. When a record is retrieved, the server returns all 5 bytes.

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"defaultDatabaseName"`

The "defaultDatabaseName" property is an optional string that specifies which database name to use when the "databaseName" property is omitted.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

`"defaultDebug"`

"defaultDebug" is an optional string that defines the default value of the "debug" property for all requests in a session. It defaults to "max".

Important

This is different than the "debug" property in that the "debug" property can be universally used in any action while the "defaultDebug" property is only set in the "createSession" action and sets the "debug" property for any action run using the session being created.

Possible values include:
- "none"
- "max"
If "defaultDebug" is omitted or set to null, it defaults to "max".
This causes the server to include the "debugInfo" property in the response.
This setting is typically used in development environments and for temporarily troubleshooting issues in production environments.
For maximum performance set "defaultDebug" to "none" .
This causes the server to omit the "debugInfo" property in the response.
This setting is typically used in production and staging environments where it is desirable to have maximum performance and minimal network traffic.

`"binaryFormat"`

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , "result", and "mapOfPropertiesToFields".
- It occurs in "params" when actions create or change values.
- It occurs in "responseOptions" when actions return values.
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields" transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"dataFormat"`

The "dataFormat" property is a case-insensitive string enum that defines the format of the "data" property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request, and another occurs in a response. They all indicate how data is formatted.

"dataFormat" in the request in "responseOptions" determines how the "data" property in the response is formatted.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.
Possible values include:
- "arrays"
  This causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
- "autoDetect"
  This is the default, and the server automatically detects the format of the data in the "sourceData" property.
"dataFormat" in the response shows the client how the server formatted the "data" property.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

`"defaultOwnerName"`

The "defaultOwnerName" property is an optional string that is supplied at "createSession". It is used by the "ownerName" property which specifies the owner account name. It defaults to the "username". When "ownerName" is omitted, the server sets "ownerName" to the value of "defaultOwnerName". However, if "defaultOwnerName" is set to the empty string, then the "ownerName" is set to the empty string.

See Object owner in the JSON DB Concepts section for an explanation of how to use the "defaultOwnerName" property to specify the owner of objects created in the session
When "ownerName" is omitted the server uses the "defaultOwnerName" property value set during login.
In "createSession" and "alterSession" when "defaultOwnerName" is omitted or set to null:
- In the JSON DB API, the server sets "defaultOwnerName" to the "username" of the logged-in user. Thus, by default, the logged-in account owns the objects it creates.
- In the JSON Hub API and JSON MQ API, the server sets "defaultOwnerName" to "admin" allowing the server to own the objects it creates.
Actions that create objects, such as "createTable" and "createIntegrationTable", can omit the "ownerName" property making the server set "ownerName" to the value of "defaultOwnerName".
When an action that creates an object sets the "ownerName" property to a valid account name, the specified account owns the created object and an account that owns an object has full management rights over the object. You can use object ownership as a simple way to control access to objects.
When "ownerName" is set to the empty string, then no account owns the object. Unowned objects can be managed by administrator accounts and by accounts assigned to roles that grant access rights to the object making it useful when you want to prevent an account from owning an object and inheriting full management rights to that object.

`"defaultResponseOptions"`

The "defaultResponseOptions" property is a "responseOptions" object. It defines a default value for "responseOptions" that is used by default in all other action calls. It defaults to an empty object.

JSON NAV allows you to choose how your program detects errors. By default, all error properties are included in each response – unless you override this behavior as shown in the example.
The example omits the error object in all responses which makes it easier for statically typed languages, such as C, C++, Java, C#, and VB, because they prefer properties to always be present. To help these languages, the "errorCode", "errorMessage", and "errorData" properties are always present whether there is an error or not.

Example

 "defaultResponseOptions": {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number",
      "variantFormat": "json"
    }

`"binaryFormat"`

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , "result", and "mapOfPropertiesToFields".
- It occurs in "params" when actions create or change values.
- It occurs in "responseOptions" when actions return values.
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields" transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"dataFormat"`

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request, and another occurs in a response. They all indicate how data is formatted.

"dataFormat" in the request in "responseOptions" determines how the "data" property in the response is formatted.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.
Possible values include:
- "arrays"
  This causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
- "autoDetect"
  This is the default, and the server automatically detects the format of the data in the "sourceData" property.
"dataFormat" in the response shows the client how the server formatted the "data" property.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

`"variantFormat"`

The "variantFormat" property tells the server how to format the values of variant fields in its response to your request.

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".

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"
}

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"
}

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

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

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

`"numberFormat"`

The "numberFormat" property is an optional, case-insensitive string enum. It defines the format of JSON numbers. The default value for "numberFormat" is the "defaultNumberFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultNumberFormat" property in the <faircom>/config/services.json file.

When "numberFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode a number assigned to a JSON property.

For example, including "numberFormat" in a "tableFieldsToJson" transform step controls if the server encodes a number in a JSON property as a number or a number embedded in a string.

Possible values:

"number"
This causes the server to return numeric values as JSON numbers, such as -18446744073709551616.000144722494 .
This is most efficient.
JSON represents numbers are base-ten numbers that may have any number of digits.
Large numbers, such as 18446744073709551616.000144722494 are known to cause problems with JSON parsers and some programming languages, such as JavaScript, which are limited to the smaller range and binary rounding errors of IEEE floating point numbers.
"string"
This returns the server to embed numeric values in JSON strings, such as "18446744073709551616.000144722494" .
This is slightly less efficient because it includes two extra double quote characters
Returning numbers embedded in strings ensures JSON parsers and programming languages will not automatically convert the number to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors. This allows your application to control how numbers are processed.
Omitted or set to null
This defaults to "number".

Example request

{
  "action": "someAction",
  "responseOptions":
  {
    "numberFormat": "string"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"variantFormat"`

The "variantFormat" property tells the server how to interpret the variant data included in a JSON Action request.

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 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".

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"
}

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"
}

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

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

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

`"defaultRetentionPeriod"`

The "defaultRetentionPeriod" property specifies how many retention units will be retained if the "retentionPeriod" property is omitted. It is used in tandem with "defaultRetentionUnit", the retention period describing how many units, and the retention unit describing what kind of unit of measurement. For example, if the "defaultRetentionPeriod" is set to 4, and the "defaultRetentionUnit" is set to "week", the server will purge messages once 4 weeks have passed by default.

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },

`"defaultRetentionPolicy"`

The "defaultRetentionPolicy" property specifies the default way in which messages are persisted if the "retentionPolicy" property is omitted. Using this property, you can configure messages to persist indefinitely, be purged according to the retention unit and period, or be immediately purged by default.

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },

`"defaultRetentionUnit"`

The "defaultRetentionUnit" property specifies the type of retention unit if the "retentionUnit" property is omitted. It is used in tandem with "defaultRetentionUnit", the retention period describing how many units, and the retention unit describing what kind of unit of measurement. For example, if the "defaultRetentionPeriod" is set to 4, and the "defaultRetentionUnit" is set to "week", the server will purge messages once 4 weeks have passed by default.

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },

`"defaultVariantFormat"`

The "defaultVariantFormat" property sets the default value of the "variantFormat" property when a JSON Action request does not include it.

`"description"`

The "description" property is an optional string that allows you to describe an object for later identification.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

`"idleConnectionTimeoutSeconds"`

The "idleConnectionTimeoutSeconds" property is an optional integer from 0 to 2147483647. It is the number of seconds that a session with no activity will stay open.

A value of 0 keeps a session open indefinitely.

`"idleCursorTimeoutSeconds"`

The "idleCursorTimeoutSeconds" property is an optional integer from 0 to 2147483647. It is the number of seconds to keep a cursor open.

Each time a cursor retrieves records, the cursor timer restarts.
A value of -1 keeps a cursor open indefinitely.
A value of 0 immediately closes a cursor after the current operation.

`"transformBufferInitialBytes"`

The "transformBufferInitialBytes" property is optional and defaults to 0. It is a positive integer that specifies the number of bytes for the session to allocate initially for its transform buffer. Omit this property or set it to 0 when you do not plan on using the "transformCodeName" property to transform the JSON returned from the "getRecords..." actions. If you plan on transforming the JSON, you can set the "transformBufferInitialBytes" property to the number of bytes that you anticipate the server will need to store the results of each transform. If the server needs more memory, it automatically increases the buffer size; thus, this property is an optimization that helps prevent the server from doing expensive memory allocations.

`"responseOptions"`

The "responseOptions" property is an optional object that configures the server to return a customized response.

None of these properties are required, but some are mutually exclusive:
- "includeFields" and "excludeFields" are mutually exclusive.
  Use "includeFields" or "excludeFields" to control which record fields are present in the data.
- "includePaths" and "excludePaths" are mutually exclusive.
  Use "includePaths" or "excludePaths" to control which JSON properties are included in the data.
A JSON path includes the JSON field name plus the path of the property within the JSON field.
Use "omit" to remove a property from a response, such as omitting "errorMessage".
Use "dataFormat" to control whether data comes back as an array of arrays or an array of objects.
Use "numberFormat" to control whether JSON numbers are rendered as digits or digits embedded in a string.
Use "variantFormat" to control how the server formats the values of variant fields in its response.

    "responseOptions": 
    { 
     "omit": ["error", "fieldDefs" ]
     "dataFormat": "arrays", 
     "numberFormat": "number",
     "includeFields": [ "name", "email" ],
     "excludeFields": [],
     "includePaths": [],
     "excludePaths": [ "email.domain" ],
     "binaryFormat": "base64",
     "variantFormat": "json"
    }

Table 2. "responseOptions" property summaries

Property

Description

Default

Type

Limits (inclusive)

binaryFormat

specifies how binary values are returned

"hex"

string

One of the following: "base64", "hex", or "byteArray".

dataFormat

specifies what format the results will be returned in

"arrays"

string

"default"

"arrays"

"objects"

excludeFields

(optional) specifies which fields are excluded in the response message

[]

When the array is empty or the property is not specified, the includeFields behavior applies

array

excludePaths

specifies which paths are excluded in the response message

[]

When the array is empty or the property is not specified, the includePaths behavior applies

array

includeFields

(optional) specifies which fields are returned in the response message

[]

When the array is empty or the property is not specified, all fields are returned

array

includePaths

specifies which paths are included in the response message

[]

When the array is empty or the property is not specified, all paths are returned

array

numberFormat

specifies how numbers are formatted in the JSON response message

"number"

string

"number"

"string"

omit

specifies which properties are excluded in the response message

{}

object

variantFormat

(optional) specifies how the server will represent the values of variant fields in its response to your request

"json"

string

"json"

"binary"

"string"

"variantObject"

`"binaryFormat"`

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , "result", and "mapOfPropertiesToFields".
- It occurs in "params" when actions create or change values.
- It occurs in "responseOptions" when actions return values.
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields" transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"dataFormat"`

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request, and another occurs in a response. They all indicate how data is formatted.

"dataFormat" in the request in "responseOptions" determines how the "data" property in the response is formatted.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.
Possible values include:
- "arrays"
  This causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
- "autoDetect"
  This is the default, and the server automatically detects the format of the data in the "sourceData" property.
"dataFormat" in the response shows the client how the server formatted the "data" property.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

`"numberFormat"`

When "numberFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode a number assigned to a JSON property.

For example, including "numberFormat" in a "tableFieldsToJson" transform step controls if the server encodes a number in a JSON property as a number or a number embedded in a string.

Possible values:

"number"
This causes the server to return numeric values as JSON numbers, such as -18446744073709551616.000144722494 .
This is most efficient.
JSON represents numbers are base-ten numbers that may have any number of digits.
Large numbers, such as 18446744073709551616.000144722494 are known to cause problems with JSON parsers and some programming languages, such as JavaScript, which are limited to the smaller range and binary rounding errors of IEEE floating point numbers.
"string"
This returns the server to embed numeric values in JSON strings, such as "18446744073709551616.000144722494" .
This is slightly less efficient because it includes two extra double quote characters
Returning numbers embedded in strings ensures JSON parsers and programming languages will not automatically convert the number to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors. This allows your application to control how numbers are processed.
Omitted or set to null
This defaults to "number".

Example request

{
  "action": "someAction",
  "responseOptions":
  {
    "numberFormat": "string"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"variantFormat"`

The "variantFormat" property tells the server how to format the values of variant fields in its response to your request.

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 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".

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"
}

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"
}

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

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

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

`"result"`

The "result" property is a required object set by the server that contains the result of an action.

Table 3. alterSession "result" property summaries

Property

Description

Type

Contents

authToken

signifies that the client is authenticated and authorized

string

0 to 255 bytes

defaultApi

indicates the value of the "api" property when "api" is omitted from an action request.

string enum

"admin"

"hub"

"mq"

"db"

defaultBinaryFormat

specifies the default value for the "binaryFormat" property, which tells the server how to parse binary data from the client when the binary format is not specified in the action request.

string

"base64"

"hex"

"byteArray"

defaultDatabaseName

specifies the default value of the "databaseName" property.

string

1 to 64 bytes

defaultDebug

indicates the default value of the "debug" property for all requests in a session.

string enum

"none"

"max"

defaultOwnerName

specifies the initial value of the "defaultOwnerName" property used by JSON APIs and FairCom's web application.

string

1 to 64 bytes

defaultResponseOptions

specifies a default value for "responseOptions" that is used by default in all other action calls. "includeFields" and "excludeFields" are mutually exclusive and "includePaths" and "excludePaths" are mutually exclusive.

object

"includeFields"

"excludeFields"

"includePaths"

"excludePaths"

"omit"

"numberFormat"

"dataFormat"

defaultResponseOptions

.binaryFormat

specifies how binary values are returned.

string enum

"base64"

"hex"

"byteArray"

defaultResponseOptions

.dataFormat

specifies what format the results will be returned in.

string enum

"arrays"

"default"

"objects"

defaultResponseOptions

.numberFormat

specifies how numbers are formatted in the JSON response message.

string enum

"number"

"string"

defaultResponseOptions

.variantFormat

indicates how the server will interpret the variant-type data included in the request.

string enum

"json"

"binary"

"string"

"variantObject"

defaultRetentionPeriod

indicates how many retention units will be retained if the "retentionPeriod" property is omitted.

integer

1 to 100

defaultRetentionPolicy

indicates the default way in which messages are persisted if the "retentionPolicy" property is omitted.

string enum

"doNotPersist"

"neverPurge"

"autoPurge"

defaultRetentionUnit

indicates the default unit of time after which the expired messages will be purged if the "retentionUnit" property is omitted.

string enum

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

defaultVariantFormat

indicates the variant format the server uses when the user omits the "variantFormat" property in a JSON action request.

string enum

"json"

"binary"

"string"

"variantObject"

description

(optional) describes an object for later identification.

string

0 to 65,500 bytes

idleConnectionTimeoutSeconds

(optional) specifies the number of seconds that a session with no activity will stay open.

integer

0 to 2147483647

idleCursorTimeoutSeconds

(optional) specifies the number of seconds to keep a cursor open.

integer

0 to 2147483647

permanentSession

indicates if the session is persisted.

boolean

true

false

serverVersion

indicates the version of the server the request was made to.

string

The name of the version of the FairCom server to which the request was made.

sessionLastAccessedTimestamp

indicates the date/time when the session was last accessed.

timestamp

An ISO 8601 timestamp

sessionStartTimestamp

indicates the date/time when the session was initiated.

timestamp

An ISO 8601 timestamp

transformBufferInitialBytes

indicates the number of bytes for the session to allocate initially for its transform buffer.

integer

0 or more bytes

username

specifies the account name of a user or application.

string

1 to 64 bytes

`"authToken"`

The "authToken" property signifies that the client is authenticated and authorized. It is required.

It is supplied by the server in response to the connect action.
Clients must include it in all subsequent requests to validate that they are authenticated and authorized. If the client does not supply the correct values, the server returns an unauthorized error.

`"defaultAPI"`

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

`"defaultBinaryFormat"`

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , "result", and "mapOfPropertiesToFields".
- It occurs in "params" when actions create or change values.
- It occurs in "responseOptions" when actions return values.
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields" transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"defaultDatabaseName"`

The "defaultDatabaseName" property is an optional string that specifies which database name to use when the "databaseName" property is omitted.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

`"defaultDebug"`

"defaultDebug" is an optional string that defines the default value of the "debug" property for all requests in a session. It defaults to "max".

Important

Possible values include:
- "none"
- "max"
If "defaultDebug" is omitted or set to null, it defaults to "max".
This causes the server to include the "debugInfo" property in the response.
This setting is typically used in development environments and for temporarily troubleshooting issues in production environments.
For maximum performance set "defaultDebug" to "none" .
This causes the server to omit the "debugInfo" property in the response.
This setting is typically used in production and staging environments where it is desirable to have maximum performance and minimal network traffic.

`"defaultOwnerName"`

See Object owner in the JSON DB Concepts section for an explanation of how to use the "defaultOwnerName" property to specify the owner of objects created in the session
When "ownerName" is omitted the server uses the "defaultOwnerName" property value set during login.
In "createSession" and "alterSession" when "defaultOwnerName" is omitted or set to null:
- In the JSON DB API, the server sets "defaultOwnerName" to the "username" of the logged-in user. Thus, by default, the logged-in account owns the objects it creates.
- In the JSON Hub API and JSON MQ API, the server sets "defaultOwnerName" to "admin" allowing the server to own the objects it creates.
Actions that create objects, such as "createTable" and "createIntegrationTable", can omit the "ownerName" property making the server set "ownerName" to the value of "defaultOwnerName".
When an action that creates an object sets the "ownerName" property to a valid account name, the specified account owns the created object and an account that owns an object has full management rights over the object. You can use object ownership as a simple way to control access to objects.
When "ownerName" is set to the empty string, then no account owns the object. Unowned objects can be managed by administrator accounts and by accounts assigned to roles that grant access rights to the object making it useful when you want to prevent an account from owning an object and inheriting full management rights to that object.

`"defaultResponseOptions"`

JSON NAV allows you to choose how your program detects errors. By default, all error properties are included in each response – unless you override this behavior as shown in the example.
The example omits the error object in all responses which makes it easier for statically typed languages, such as C, C++, Java, C#, and VB, because they prefer properties to always be present. To help these languages, the "errorCode", "errorMessage", and "errorData" properties are always present whether there is an error or not.

Example

 "defaultResponseOptions": {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number",
      "variantFormat": "json"
    }

`"binaryFormat"`

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , "result", and "mapOfPropertiesToFields".
- It occurs in "params" when actions create or change values.
- It occurs in "responseOptions" when actions return values.
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields" transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"dataFormat"`

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request, and another occurs in a response. They all indicate how data is formatted.

"dataFormat" in the request in "responseOptions" determines how the "data" property in the response is formatted.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.
Possible values include:
- "arrays"
  This causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
- "autoDetect"
  This is the default, and the server automatically detects the format of the data in the "sourceData" property.
"dataFormat" in the response shows the client how the server formatted the "data" property.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

`"variantFormat"`

The "variantFormat" property tells the server how to format the values of variant fields in its response to your request.

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 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".

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"
}

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"
}

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

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

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

`"numberFormat"`

When "numberFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode a number assigned to a JSON property.

For example, including "numberFormat" in a "tableFieldsToJson" transform step controls if the server encodes a number in a JSON property as a number or a number embedded in a string.

Possible values:

"number"
This causes the server to return numeric values as JSON numbers, such as -18446744073709551616.000144722494 .
This is most efficient.
JSON represents numbers are base-ten numbers that may have any number of digits.
Large numbers, such as 18446744073709551616.000144722494 are known to cause problems with JSON parsers and some programming languages, such as JavaScript, which are limited to the smaller range and binary rounding errors of IEEE floating point numbers.
"string"
This returns the server to embed numeric values in JSON strings, such as "18446744073709551616.000144722494" .
This is slightly less efficient because it includes two extra double quote characters
Returning numbers embedded in strings ensures JSON parsers and programming languages will not automatically convert the number to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors. This allows your application to control how numbers are processed.
Omitted or set to null
This defaults to "number".

Example request

{
  "action": "someAction",
  "responseOptions":
  {
    "numberFormat": "string"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"variantFormat"`

The "variantFormat" property tells the server how to format the values of variant fields in its response to your request.

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 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".

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"
}

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"
}

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

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

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

`"defaultRetentionPeriod"`

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },

`"defaultRetentionPolicy"`

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },

`"defaultRetentionUnit"`

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },

`"defaultVariantFormat"`

The "defaultVariantFormat" property sets the default value of the "variantFormat" property when a JSON Action request does not include it.

`"description"`

The "description" property is an optional string that allows you to describe an object for later identification.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

`"idleConnectionTimeoutSeconds"`

The "idleConnectionTimeoutSeconds" property is an optional integer from 0 to 2147483647. It is the number of seconds that a session with no activity will stay open.

A value of 0 keeps a session open indefinitely.

`"idleCursorTimeoutSeconds"`

The "idleCursorTimeoutSeconds" property is an optional integer from 0 to 2147483647. It is the number of seconds to keep a cursor open.

Each time a cursor retrieves records, the cursor timer restarts.
A value of -1 keeps a cursor open indefinitely.
A value of 0 immediately closes a cursor after the current operation.

`"permanentSession"`

The "permanentSession" property is an optional Boolean that indicates if a session is permanent. It defaults to false.

Important

Before you can create permanent sessions, you must add "enablePermanentJsonApiSessions": true to the "jsonActionApiDefaults" section of the <faircom>/config/services.json file.

If "permanentSession" is set to true when "createSession" is called, the server sets the authtoken as permanent. The authtoken is associated with the settings and authorizations of the user who created the session. It is always valid even after the server restarts. A permanent authToken works like an API Key and authenticates an application without the need for a username/password or a client certificate. Multiple applications can use the same permanent authToken.

Warning

A permanent "authToken" is potentially less secure than a temporary one.

A permanent "authToken" never becomes invalid, which makes it easier for an attacker to find it using brute force.
A permanent "authToken" is persisted by an application, which increases the opportunity for an attacker to find it.
A permanent "authToken" allows each application server to share the same session, which potentially allows an attacker to change session settings for all application servers.

When you set the "permanentSession" property to true in "createSession" , it creates a permanent session and returns a permanent "authToken" .
Developers and applications can use a permanent authToken in JSON actions without needing to call createSession to get a temporary authToken.
You must protect a permanent "authToken" as you would a password or API key because it represents a permanently authenticated server session.
A permanent session does not expire. You can also prevent a temporary session from expiring by setting its "idleConnectionTimeoutSeconds" property to 0.
A permanent "authToken" uses the authorization and settings of the account that originally created the session. All actions performed in the session are performed using that account's authorizations, and account settings, such as its default database and owner.
You can use "alterSession" to modify the settings of a permanent session, but you cannot use it to turn a temporary session into a permanent session.
If multiple application servers use the same permanent "authToken", they share the same permanent session settings. Consider the following:
- If one application server uses "alterSession" to change a permanent session's settings, the other application servers automatically use the new settings. To avoid confusion and errors, applications must specify all JSON action property values and not rely on session defaults.
- You cannot use different sessions to determine which app server executes an action. This makes troubleshooting more difficult.
- An application must create and use a transaction to protect the visibility and integrity of multiple operations from other applications. This is true for permanent and temporary sessions.
The FairCom server securely stores each permanent "authToken" in the encrypted faircom.fcs file.

`"serverVersion"`

The "serverVersion" property indicates which version of the FairCom server the request was made to.

  "result": {
    "sessionStartTimestamp": "2025-08-28T15:44:56",
    "sessionLastAccessedTimestamp": "2025-08-28T18:07:07",
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4,
    "serverVersion": "FairCom EDGE Server - V4.2.4.109(Build-250819)"
  },

`"sessionLastAccessedTimestamp"`

The "sessionLastAccessedTimestamp" property indicates the date/time when the session was last accessed.

"result": {
  "sessionStartTimestamp": "2025-08-27T20:26:25",
  "sessionLastAccessedTimestamp": "2025-08-27T20:56:25"
  },

`"sessionStartTimestamp"`

The "sessionStartTimestamp" property indicates the date/time when the session was first initialized.

"result": {
  "sessionStartTimestamp": "2025-08-27T20:26:25",
  "sessionLastAccessedTimestamp": "2025-08-27T20:56:25"
  },

`"transformBufferInitialBytes"`

`"username"`

The "username" property is a required string from 1 to 64 bytes. It is the account name of a user or application.

It is required by the "createSession" action for authentication.
All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.
In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.
Unlike other property names, such as "databaseName", "username" is all lowercase.
A zero-length username is invalid.

Note

See System limits for requirements of this and all other system properties.

"alterSession" (JSON Action)

Alter the settings of a session

Request examples

Change timeouts

Change many defaults simultaneously

Maximal

Response examples

Success

Invalid session "id"/"authToken" failure

"params"

"defaultAPI"

"defaultBinaryFormat"

Note

Note

"defaultDatabaseName"

"defaultDebug"

Important

"binaryFormat"

Note

Note

"dataFormat"

"defaultOwnerName"

"defaultResponseOptions"

Example

"binaryFormat"

Note

Note

"dataFormat"

"variantFormat"

"numberFormat"

"variantFormat"

"defaultRetentionPeriod"

"defaultRetentionPolicy"

"defaultRetentionUnit"

"defaultVariantFormat"

"description"

"idleConnectionTimeoutSeconds"

"idleCursorTimeoutSeconds"

"transformBufferInitialBytes"

"responseOptions"

"binaryFormat"

Note

Note

"dataFormat"

"numberFormat"

"variantFormat"

"result"

"authToken"

"defaultAPI"

"defaultBinaryFormat"

Note

Note

"defaultDatabaseName"

"defaultDebug"

Important

"defaultOwnerName"

"defaultResponseOptions"

Example

"binaryFormat"

Note

Note

"dataFormat"

"variantFormat"

"numberFormat"

"variantFormat"

"defaultRetentionPeriod"

"defaultRetentionPolicy"

"defaultRetentionUnit"

"defaultVariantFormat"

"description"

"idleConnectionTimeoutSeconds"

"idleCursorTimeoutSeconds"

"permanentSession"

Important

Warning

"serverVersion"

"sessionLastAccessedTimestamp"

"sessionStartTimestamp"

"transformBufferInitialBytes"

"username"

`"alterSession"` (JSON Action)

Invalid session `"id"`/`"authToken"` failure

`"params"`

`"defaultAPI"`

`"defaultBinaryFormat"`

`"defaultDatabaseName"`

`"defaultDebug"`

`"binaryFormat"`

`"dataFormat"`

`"defaultOwnerName"`

`"defaultResponseOptions"`

`"binaryFormat"`

`"dataFormat"`

`"variantFormat"`

`"numberFormat"`

`"variantFormat"`

`"defaultRetentionPeriod"`

`"defaultRetentionPolicy"`

`"defaultRetentionUnit"`

`"defaultVariantFormat"`

`"description"`

`"idleConnectionTimeoutSeconds"`

`"idleCursorTimeoutSeconds"`

`"transformBufferInitialBytes"`

`"responseOptions"`

`"binaryFormat"`

`"dataFormat"`

`"numberFormat"`

`"variantFormat"`

`"result"`

`"authToken"`

`"defaultAPI"`

`"defaultBinaryFormat"`

`"defaultDatabaseName"`

`"defaultDebug"`

`"defaultOwnerName"`

`"defaultResponseOptions"`

`"binaryFormat"`

`"dataFormat"`

`"variantFormat"`

`"numberFormat"`

`"variantFormat"`

`"defaultRetentionPeriod"`

`"defaultRetentionPolicy"`

`"defaultRetentionUnit"`

`"defaultVariantFormat"`

`"description"`

`"idleConnectionTimeoutSeconds"`

`"idleCursorTimeoutSeconds"`

`"permanentSession"`

`"serverVersion"`

`"sessionLastAccessedTimestamp"`

`"sessionStartTimestamp"`

`"transformBufferInitialBytes"`

`"username"`