Message tree mapping in the JSON domain

When reading a JSON message, the parser builds a message tree from the input bit stream by mapping JSON values to corresponding message tree element types. When serializing a message tree into the output bit stream, tree element types are mapped to JSON value types.

When you use the Graphical Data Mapping editor to transform a JSON message, ensure that the JSON element names that you define by using the Add User Defined function are valid according to the XML element naming rules. JSON allows a wider range of characters than XML, for example a JSON object could include the @ character, however, the Graphical Data Mapping editor only allows element names that are valid in XML or XPath.

The following tables show how JSON message values are mapped to message tree element types:

JSON bit stream to message tree value mapping

The JSON parser maps JSON values to message tree element types according to the rules in the following table:

JSON value present in bit stream Parsed as
String CHARACTER

JSON Number value presented as:

  • A minus sign prefix if the value is negative
  • At least one digit, which can be zero
  • No dot fractional part
  • No exponent
 INTEGER

JSON Number value presented as:

  • A minus sign prefix if the number is negative
  • At least one digit in the integer part, which can be zero
  • Either or both of:
  • A dot and at least one digit in the fractional part, which can be zero
  • An exponent using uppercase 'E' or lowercase 'e', an optional plus or minus sign, and at least one digit
 FLOAT
Boolean BOOLEAN
Null NULL

Message tree to JSON message value mapping

The JSON serializer maps message tree elements to JSON value types according to the rules in the following table:

Message tree Element type JSON Domain serializes as
  JSON type Format
BIT String Any number of 0 and 1s
BLOB String Even number of hexadecimal digits
CHARACTER String Char data with JSON string escaping for the characters that are listed below:
  • " - quotation mark (U+0022)
  • \ - reverse solidus (U+005C)
  • / - solidus (U+002F)
  • backspace (U+0008)
  • form feed (U+000C)
  • line feed (U+000A)
  • carriage return (U+000D)
  • tab (U+0009)
See https://tools.ietf.org/html/rfc7159#section-7 for more details.
DATE String The standard ESQL string representation, 'yyyy-mm-dd'
TIME, GMTTIME String The standard ESQL string representation, 'hh:mm:ss.ffffff'
INTEGER Number
  • A minus sign prefix if the number is negative
  • At least one digit, which can be zero
  • No dot fractional
  • No exponent
FLOAT Number
  • A minus sign prefix if the number is negative
  • At least one digit in the integer part, which can be zero
  • At least one digit in the fractional part, which can be zero
  • An exponent part using uppercase 'E', a plus or minus sign, and at least one digit
DECIMAL Number
  • A minus sign prefix if the number is negative
  • At least one digit in the integer part, which can be zero
  • At least one digit in the fractional part, which can be zero

Decimal literals ‘NAN', ‘INF', and so on, are not supported when serializing to JSON.
BOOLEAN Boolean true or false

The serializer only serializes Boolean logical tree elements with true or false values; unknown is not supported
NULL Null Null
ROW Object

Note: Assigning a ROW directly to a JSON Domain tree does not produce JSON arrays.

DECLARE myRow ROW;
SET myRow.rowData[1].fieldOne = 'Row1Field1';
SET myRow.rowData[1].fieldTwo = 'Row1Field2';
SET myRow.rowData[2].fieldOne = 'Row2Field1';
SET myRow.rowData[2].fieldTwo = 'Row2Field2';
SET OutputRoot.JSON.Data.aRow = myRow;

Produces the following JSON bit stream

"aRow":{
  "rowData": {"fieldOne":"Row1Field1","fieldTwo":"Row1Field2"},"
  "rowData": {"fieldOne":"Row2Field1","fieldTwo":"Row2Field2"}
}
ROW Array

To produce a JSON array from a ROW type the JSON.Array field would also be set.

SET OutputRoot.JSON.Data.aRow = myRow;
SET OutputRoot.JSON.Data.aRow TYPE = JSON.Array;

Produces the following JSON bit stream

"aRow":[
  {"fieldOne":"Row1Field1","fieldTwo":"Row1Field2"},
  {"fieldOne":"Row2Field1","fieldTwo":"Row2Field2"}
]