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:
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 Type | JSON Type | Notes |
---|---|---|
Int | Number | |
Long | Number | |
Float | Number | |
Double | Number | |
Boolean | true or false | |
String | String | |
Uri | String | As defined by RFC 3986. |
DateTime | String | See Date / Time Formatting. |
Date | String | See Date / Time Formatting. |
Time | String | See Date / Time Formatting. |
Duration | Number | Same as an ICWS Double indicating the number of seconds. |
GUID | String | See Globally Unique Identifier (GUID). |
List | Array | |
Complex Types | Object | See Complex Types Versus Dictionaries. |
Dictionary | Object | See Complex Types Versus Dictionaries. |
Enumeration | Number | The enum's integer value. See Enumerations. |
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.
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 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:
YYYYMMDD
hhmmssZ
or hhmmss.fffZ
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.
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" }