See information about the latest product version
JSON parser and domain
JSON (JavaScript Object Notation) is a simple data-interchange format based on a subset of the JavaScript programming language.
WebSphere® Message Broker provides support for a JSON domain. Messages in the JSON domain are processed by the JSON parser and serializer. The JSON parser interprets a bit stream using the JSON grammar, and generates a corresponding JSON domain logical message tree in the broker. When processing data for output, the JSON serializer generates a JSON formatted bit stream from a JSON domain logical message tree.
The JSON parser and serializer do not support message validation because JSON message modeling is not supported by the broker.
To enable function that becomes available in WebSphere Message Broker fix packs, use the -f parameter on the mqsichangebroker command. For more information, see mqsichangebroker command.
- Objects (name-value pairs) with the following types:
- String
- Number
- Boolean
- Null
- Ordered collections of values (arrays)
For more information about JSON message structure, see JSON message details.
- UTF-8
- UTF-16BE
- UTF-16LE
- UTF-32BE
- UTF-32LE
If a UTF-* CCSID is explicitly specified, the JSON parser tolerates the corresponding Byte Order Mark (BOM) at the beginning of the data stream.
JSON data streams are parsed into a logical message tree under the Data element below the JSON parser root. The logical tree structure is shown in the Example JSON message.
The Data element can be accessed and manipulated from ESQL as JSON.Data, from Java™ as JSON/Data, from PHP as JSON->Data, or from XPath as $Body/Data. The JSON parser issues an error if a bit stream is not formatted according to the JSON grammar.
The JSON serializer serializes message trees into a JSON format data stream. The CCSID can be defined by either the broker properties tree, or by transport headers in the message assembly. If no CCSID is defined, the serializer defaults to the queue manager default CCSID for all nodes except HTTP nodes, which default to UTF-8 encoding.
When the JSON serializer is invoked through an ASBITSTREAM function call, the CCSID is defined by the CCSID parameter. If no CCSID parameter is provided, or if the value is set to 0, the JSON serializer defaults to using UTF-8 encoding.
To process messages with the JSON parser, select JSON as the Message Domain on the relevant node in the message flow. The Mapping node and the XSLTransform node do not support the JSON domain.
The broker sets the HTTP Content-Type header to application/json when serializing a JSON message tree, unless an explicit value is set by the message flow.
JSON objects are modeled in the broker message tree as a sequence of NameValue elements. The parser builds the message tree in the order in which it encounters the members in the bit stream. The serializer writes the object members into the bit stream in the tree order.
- An array containing simple values; for example:
"array1" : [ "thing1", 1 ]
The following message tree is produced:(0x01001000:Array): array1 = ( (0x03000000:NameValue):Item = 'thing1' (CHARACTER) (0x03000000:NameValue):Item = 1 (INTEGER) )
The JSON parser assigns the name Item to the NameValue elements.
- An array containing objects; for example:
"array2" : [ {"a" : 1}, {"b" : 2} ]
The following message tree is produced:(0x01001000:Array):array2 = ( (0x01000000:Object):Item = ( (0x03000000:NameValue):a = 1 (INTEGER) ) (0x01000000:Object):Item = ( (0x03000000:NameValue):b = 2 (INTEGER) ) )
- A multidimensional array; for example:
"array3" : [ [1.1], [2.1] ]
The following message tree is produced:(0x01001000:Array):array3 = ( (0x01001000:Array):Item = ( (0x03000000:NameValue):Item = 1.1E+0 (FLOAT) ) (0x01001000:Array):Item = ( (0x03000000:NameValue):Item = 2.1E+0 (FLOAT) ) )
Example JSON message
The following example shows a simple JSON message:
{
"name" : "John Doe",
"age" : -1.0,
"known" : false,
"address" : { "street" : null,
"city" : "unknown" },
"belongings" : ["item1", "item2", "item3"]
}
This JSON input produces the following broker logical message tree:
(0x01000000:Object):JSON = ( ['json' : 0xd55fc8]
(0x01000000:Object):Data = (
(0x03000000:NameValue):name = 'John Doe' (CHARACTER)
(0x03000000:NameValue):age = -1E+0 (FLOAT)
(0x03000000:NameValue):known = FALSE (BOOLEAN)
(0x01000000:Object ):address = (
(0x03000000:NameValue):street = NULL
(0x03000000:NameValue):city = 'unknown' (CHARACTER)
)
(0x01001000:Array ):belongings = (
(0x03000000:NameValue):Item = 'item1' (CHARACTER)
(0x03000000:NameValue):Item = 'item2' (CHARACTER)
(0x03000000:NameValue):Item = 'item3' (CHARACTER)
)
)
)