Objectivity REST : Objectivity/DB Data Types
Objectivity/DB Data Types
An Objectivity/DB schema defines the contents of a particular federated database by describing every class whose objects can be stored in that federated database. You can use any of the supported Objectivity/DB data types as attribute types when creating your class descriptions. The supported types include built-in basic data types for numeric, Boolean, and character data, as well as system classes that define more complex data structures, such as strings and collections; see Chapter 13, “Objectivity/DB Schema,” in Objectivity/DB Administration for general information about schema.
This section provides details about how to use the supported types when creating or updating class descriptions using JSON in REST requests. Also included are examples of some of the formats required when supplying values for the data types.
Basic Types
Table 2‑1: Basic Data Types 
Family of Data Types
Description
JSON Input and Output
Boolean
Values that are either true or false
   Binary encoding
Byte
Data type for:
8-bit Boolean values
   
{
  "attributeName": "available",
  "logicalType": "boolean",
  "encoding": "binary",
  "storage": "byte"
}
Character
Characters within a string
   Binary encoding
B8, B16,
B32
Data types for:
8-bit, 16-bit, and 32-bit character values.
{
  "attributeName": "state",
  "logicalType": "character",
  "encoding": "binary",
  "storage": "b8"
}
 
"storage": "b8"
"storage": "b16"
"storage": "b32"
Integer
Signed or unsigned whole numbers
   Signed encoding
 
B8, B16,
B32, B64
Data types for:
Signed 8-bit, 16-bit, 32-bit, and 64-bit integer values.
{
  "attributeName": "doors",
  "logicalType": "integer",
  "encoding": "signed",
  "storage": "b32"
}
 
"storage": "b8"
"storage": "b16"
"storage": "b32"
"storage": "b64"
   Unsigned encoding
B8, B16,
B32, B64
Data types for:
Unsigned 8-bit, 16-bit, 32-bit, and 64-bit integer values.
{
  "attributeName": "seatingCapacity",
  "logicalType": "integer",
  "encoding": "unsigned",
  "storage": "b8"
}
 
"storage": "b8"
"storage": "b16"
"storage": "b32"
"storage": "b64"
Real
Real numbers with a fractional part
   IEEE encoding
B32, B64
Data types for:
32-bit and 64-bitreal (floating-point) values.
{
  "attributeName": "rateFactor",
  "logicalType": "real",
  "storage": "b32"
}
 
"storage": "b32"
"storage": "b64"
String Types
Table 2‑2: String Types 
Family of Data Types
Description
JSON Input and Output
String
Sequences of characters
   Byte encoding
Fixed,
Variable,
Optimized
Data types for:
Strings that use an 8-bit character encoding such as ASCII or ISO-Latin1, and are either fixed-length, variable-length, or optimized for (but not limited to) a particular length.
{
  "attributeName": "state",
  "logicalType": "string",
  "encoding": "byte",
  "storage": "fixed",
  "fixedLength": 2
}
 
"storage": "fixed"
"storage": "variable"
"storage": "optimized"
   Utf8 encoding
   Utf16 encoding
   Utf32 encoding
Fixed,
Variable,
Optimized
Data types for:
Strings that use Unicode UTF-8, UTF-16, or UTF-32 character encoding, and are either fixed-length, variable-length, or optimized for (but not limited to) a particular length.
{
  "attributeName": "name",
  "logicalType": "string",
  "encoding": "utf8",
  "storage": "variable"
}
 
"encoding": "utf8"
"encoding": "utf16"
"encoding": "utf32"
 
"storage": "fixed"
"storage": "variable"
"storage": "optimized"
Date-Time Types
Table 2‑3: Date-Time Types 
Family of Data Types
Description
JSON Input and Output
Date
Dates on the Gregorian calendar, with day precision
   OBJY encoding
Data type for:
4-byte date values from January 1, 0001 to December 31, 9999.
{
  "attributeName": "finalized",
  "logicalType": "date",
  "encoding": "objy"
}
Time
Times in the 24-hour clock format, with 100-microsecond precision
   OBJY encoding
Data type for:
4-byte time values from 00:00:00.0000 (midnight) to 23:59:59.9999.
{
  "attributeName": "militaryTime",
  "logicalType": "time",
  "encoding": "objy"
}
DateTime
Datetimes (timestamps) with 100-nanosecond precision
   OBJY encoding
Datetime or Datetime with time-zone offset
Data type for:
Datetime values from January 1, 0001, 00:00:00.0000000 to December 31, 9999, 23:59:59.9999999.
 
Storage options support:
8-byte values expressed either in the local time standard or in the Coordinated Universal Time (UTC) standard.
16-byte values representing a local time in a time zone that is expressed as an offset (number of minutes between local time and UTC).
{
  "attributeName": "timestamp",
  "logicalType": "datetime",
  "encoding": "objy",
  "storage": "datetime"
}
 
"storage": "datetime"
"storage": "datetimeoffset"
Interval
Timespans between two dates, times or datetimes, with 100 nanosecond precision
   OBJY encoding
Data type for:
8-byte interval values from 5,000,000 days to -5,000,000 days.
{
  "attributeName": "deltaTime",
  "logicalType": "interval",
  "encoding": "objy"
}
Reference and Embedded Types
Table 2‑4: Reference and Embedded Types 
Family of Data Types
Description
JSON Input and Output
Reference
Object references to persistent instances of a referenceable schema class
References encapsulate the object identifier (OID) that uniquely identifies a referenceable object in a federated database.
Data type for:
Reference attributes.
To-one unidirectional relationships.
{
 "attributeName": "currentRental",
 "logicalType": "reference",
 "referencedClass": "FleetData.RentalContract"
}
Data type for:
To-one bidirectional relationships.
{
  "attributeName": "atStall",
  "logicalType": "reference",
  "referencedClass": "FleetData.Stall",
  "inverseAttribute": "occupiedBy"
}
Object (Embedded)
Values that are objects of embeddable schema classes
When an object is embedded, its attributes are stored among the attributes of the enclosing object.
Data type for:
Embedded-object attributes.
{
  "attributeName": "corporateAddress",
  "logicalType": "object",
  "class": "FleetData.Address"
}
Collections
A collection is a grouping of some number (possibly zero) of elements. Support is provided for three collection primitives:
Ordered grouping of potentially non-unique elements. Elements are maintained in the order in which they were added to the collection.
Ordered or unordered grouping of unique elements. Organization of elements is controlled by the collection.
Ordered or unordered grouping of elements that are key-value pairs, where the keys must be unique within the collection, although they may lead to non-unique values. Organization of elements is controlled by the collection.
Collection Elements
Element specifications define the elements of a list or set. A map requires both a key specification and an element specification. The following table provides examples of both.
Table 2‑5: Examples of Element and Key Specifications
Sample Element Specifications
 
Bidirectional relationship elements
"elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.Stall",
    "inverseAttribute": "location"
  }
Date elements
 "elementSpecification": {
    "logicalType": "date",
    "encoding": "objy"
  }
String elements
"elementSpecification": {
    "logicalType": "string",
    "encoding": "utf8",
    "storage": "variable"
}
Sample Key Specifications
 
String keys
 "keySpecification": {
    "logicalType": "string",
    "encoding": "byte",
    "storage": "variable"
  }
Object keys
  "keySpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.RentalContract"
  }
Collection Implementations
Every collection has an internal data structure, or implementation. In general, a collection’s implementation supports a particular combination of features, such as the number and type of elements; whether the elements are ordered, unordered, unique, or nonunique; whether the collection is optimized for very many or very few elements; and so on.
The federated database provides several built-in implementation types for each type of collection. For details about the built-in types for each collection primitive, see Lists, Maps, and Sets, below.
Note:For a current list of the collection implementations that you can specify explicitly, run the ListCollections tool at a command prompt—for example,
objy ListCollections
Lists
A list attribute is defined by the list logical type. An element specification indicates the type of the list’s elements.
By default, a list attribute provides storage for a variable number of elements. You may optionally configure a list attribute to provide storage for a fixed number of elements.
By default, a list attribute selects a built-in implementation implicitly, based on the specified number and type of elements. You may explicitly request a particular list-implementation type by name. An error occurs if the requested list implementation is incompatible with the specified element specification or storage option.
A list attribute models a to-many relationship when the list’s elements are references to objects of a schema class. If you configure these references to have an inverse attribute, the relationship is bidirectional; otherwise the relationship is unidirectional.
The following table summarizes the built-in implementations that are currently supported for lists. An appropriate unnamed implementation is selected by default unless a named implementation is explicitly requested.
 
Table 2‑6: Built-in Implementation Types for Lists
Built-in List Implementation
Implementation Type Name
Element Type
Storage
Description
Variable array
Any type except a collection type
Variable
Array with a variable number of elements of the specified type.
Fixed-size array
Any type except a collection type
Fixed size
Array with a fixed number of elements of the specified type.
Scalable list
TreeListOfReferences
Reference
Variable
B+ tree for a variable number (possibly millions) of elements that are references to objects of a schema class.
The examples in the following table shows the syntax for defining and displaying a list attribute.
 
Table 2‑7: Array, List, and Relationship Types  
Family of Data Types
Description
JSON Input
JSON Output
List
Ordered grouping of elements that may be non-unique
 
Data types for:
Arrays of elements such as dates, with fixed or variable storage
{
  "attributeName": "highVolumeDates",
  "logicalType": "list",
  "storage": "variable",
  "elementSpecification": {
    "logicalType": "date",
    "encoding": "objy"
  }
}
 
"storage": "variable"
"storage": "fixedsize"
"storage": "fixed"
  "fixedLength": 5
Same as input
 
Data types for:
Unidirectional relationships to referenced persistent objects, with fixed or variable storage
 
{
  "attributeName": "stalls",
  "logicalType": "list",
  "storage": "variable",
  "elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.Stall"
  }
}
 
"storage": "variable"
"storage": "fixedsize"
"storage": "fixed"
  "fixedLength": 5
Same as input
 
Data types for:
Bidirectional relationships to referenced persistent objects, with fixed or variable storage
{
  "attributeName": "stalls",
  "logicalType": "list",
  "storage": "variable",
  "elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.Stall",
    "inverseAttribute": "location"
  }
}
 
"storage": "variable"
"storage": "fixedsize"
"storage": "fixed"
  "fixedLength": 5
Same as input
 
Data types for:
Scalable lists of references to persistent objects (explicit collection-implementation type)
{
  "attributeName": "models",
  "logicalType": "list",
  "collectionTypeName": "TreeListOfReferences",
  "elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.VehicleModel"
  }
}
{
  "attributeName": "models",
  "logicalType": "list",
  "storage": "variable",
  "collectionTypeName": "TreeListOfReferences",
  "elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.VehicleModel"
  }
}
Maps
A map attribute is defined by the map logical type. Because a map’s elements are key-value pairs, a map attribute definition must include both of the following:
A key specification to indicate the type of the keys, which may be either strings (for a name map) or references to objects of a schema class (for an object map).
An element specification to indicate the type of the values, which must be references to objects of a schema class.
A map attribute always provides storage for a variable number of key-value pairs. An error occurs if you attempt to configure a map attribute’s storage explicitly.
A map attribute uses the built-in map-implementation type that you request explicitly by name. An error occurs if the requested map implementation is incompatible with the key or element specification.
A map attribute models a to-many relationship because its elements are references to persistent objects. These references may be unidirectional or bidirectional.
The following table summarizes the built-in implementations that are currently supported for maps.
 
Table 2‑8: Built-in Implementation Types for Maps
Built-in Map Implementation
Implementation Type Name
Key Type
Value Type
Description
Unordered object map
HashMapOfReferences
Reference
Reference
Hashing mechanism for a variable number (possibly millions) of unsorted keys that are unique references to objects of a schema class. Hash values are computed from the identifiers of the referenced objects.
Sorted object map
TreeMapOfReferences
Reference
Reference
B+ tree for a variable number (possibly millions) of keys that are unique references to objects of a schema class. Elements are sorted in increasing order by the identifiers (OIDs) of the referenced objects.
Name map
NameToReferenceMap
String
Reference
Dictionary for a variable number (up to about 10,000) of unique strings, each paired with a reference to an object of a schema class. Not optimized for scalability.
The examples in the following table shows the syntax for defining and displaying a map attribute.
   
Table 2‑9: Map Types 
Family of Data Types
Description
JSON Input and Output
Map
Grouping of key-element pairs. Keys are unique; values may be non-unique. Keys may be ordered or unordered.
Data types for:
Name maps with string keys leading to referenced objects
{
  "attributeName": "customers",
  "logicalType": "map",
  "collectionTypeName": "NameToReferenceMap",
  "keySpecification": {
    "logicalType": "string",
    "encoding": "byte",
    "storage": "variable"
  },
  "elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.Customer"
  }
}
 
Data types for:
Unordered object maps with references to persistent objects as keys and values
{
  "attributeName": "customers",
  "logicalType": "map",
  "collectionTypeName": "HashMapOfReferences",
  "keySpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.RentalContract"
  },
  "elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.Customer"
  }
}
 
Data types for:
Sorted object maps with references to persistent objects as keys and values
{
  "attributeName": "customers",
  "logicalType": "map",
  "collectionTypeName": "TreeMapOfReferences",
  "keySpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.RentalContract"
  },
  "elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.Customer"
  }
}
 
Sets
A set attribute is defined with the set logical type. An element specification indicates the type of the set’s elements, which must be references to objects of a schema class.
A set attribute always provides storage for a variable number of elements. An error occurs if you attempt to configure a set attribute’s storage explicitly.
A set attribute uses the built-in set-implementation type that you request explicitly by name. An error occurs if the requested set implementation is incompatible with the key or element specification.
A set attribute models a to-many relationship because its elements are references to persistent objects. These references may be unidirectional or bidirectional.
The following table summarizes the built-in implementations that are currently supported for sets.
      
Table 2‑10: Built-in Implementation Type for Sets
Built-in Set Implementation
Implementation Type Name
Element Type
Description
Unordered set
HashSetOfReferences
Reference
Hashing mechanism for a variable number (possibly millions) of unsorted elements that are unique references to objects of a schema class. Hash values are computed from the identifiers of the referenced objects.
Sorted set
TreeSetOfReferences
Reference
B+ tree for a variable number (possibly millions) of elements that are unique references to objects of a schema class. Elements are sorted in increasing order by the identifiers (OIDs) of the referenced objects.
The examples in the following table shows the syntax for defining and displaying a set attribute.
 
Table 2‑11: Set Types 
Family of Data Types
Description
JSON Input and Output
Set
Grouping of unique elements, which may be ordered or unordered
Data types for:
Unordered sets of references to persistent objects
{
  "attributeName": "pendingPickups",
  "logicalType": "set",
  "collectionTypeName": "HashSetOfReferences",
  "elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.Reservation"
  }
}
 
Data types for:
Sorted sets of references to persistent objects
{
  "attributeName": "pendingPickups",
  "logicalType": "set",
  "collectionTypeName": "TreeSetOfReferences",
  "elementSpecification": {
    "logicalType": "reference",
    "referencedClass": "FleetData.Reservation"
  }
}