Expand All Collapse All

Representation Object Format

Representations in ICWS are transmitted as JSON values. This page describes how ICWS types and concepts are formatted in JSON.

This topic contains the following sections:

Basic Types

The ICWS types are mapped to JSON types as described in the table below. All JSON values are formatted according to RFC 4627. This includes handling of special characters in all JSON strings.

ICWS TypeJSON TypeNotes
IntNumber
LongNumber
FloatNumber
DoubleNumber
Booleantrue or false
StringString
UriStringAs defined by RFC 3986.
DateTimeStringSee Date / Time Formatting.
DateStringSee Date / Time Formatting.
TimeStringSee Date / Time Formatting.
DurationNumberSame as an ICWS Double indicating the number of seconds.
GUIDStringSee Globally Unique Identifier (GUID).
ListArray
Complex TypesObjectSee Complex Types Versus Dictionaries.
DictionaryObjectSee Complex Types Versus Dictionaries.
EnumerationNumberThe enum's integer value. See Enumerations.

Complex Types Versus Dictionaries

In ICWS, complex types and dictionary types are both represented as JSON objects. The formatting for ICWS complex types is the same as for ICWS dictionaries. Complex types have a fixed set of members, called properties. Dictionaries, on the other hand, do not have a defined list of members but instead have key-value pairs.

Derived Complex Types

Complex types may be derived from other complex types. In general derived types are used to provide different sets of properties for the same representation. When derived complex types are in use, the complex types will have a special property __type (with two underscore characters) which is used to distinguish absolutely which type is being used. This property is required and must be included for all derived types. The value of the __type property is constant for each type and is defined in the documentation for each derived type.

When displayed in the documentation, the label "Multiple Options:" will precede the name of the base type. Expanding this line will show each valid derived type indicated by "[option]". For more information on the documentation of derived complex types, see Multiple Options

Example usage of derived complex types can be found in the request for POST /icws/connection which includes multiple authentication types. Another example is in the response to GET /icws/{sessionId}/messaging/messages where all messages are derived from a common message base.

Date / Time Formatting

Date and Time formats are expressed in JSON objects as string values with a specified format. All values are always expressed in Coordinated Universal Time (UTC). The format, which is a strict subset of ISO 8601, is as follows:

Date
YYYYMMDD
Time
hhmmssZ or hhmmss.fffZ
Date Time
YYYYMMDDThhmmssZ or YYYYMMDDThhmmss.fffZ

The 'T', 'Z', and '.' characters are literal and YYYY, MM, DD, hh, mm, ss are all fixed width representations. If the value does not have millisecond precision, the '.' and millisecond digits are omitted.

YYYY
The year as a 4-digit number.
MM
The month as a 2-digit number from 01 to 12.
DD
The day as a 2-digit number from 01 to 31.
hh
The hour as a 2-digit number from 00 to 23.
mm
The minute as a 2-digit number from 00 to 59.
ss
The second as a 2-digit number from 00 to 59.
fff
The milliseconds as a 3-digit number from 000 to 999.

Globally Unique Identifier (GUID)

Globally Unique Identifiers (GUIDs), also known as Universally Unique Identifiers (UUIDs), are used as unique identifiers. At their core, GUIDs are 128-bit numbers, but they will be represented in ICWS as a string of hexadecimal digits in the format of 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', groups of 8, 4, 4, 4 and 12 separated by hyphens. 

{
    "exampleGuid": "10f5bacc-08cc-4e65-a64d-de2e77a237db"
}