JSON messaging in IBM MQ estates usually means microservices exchanging business events as JSON documents through REST put/get, or applications writing UTF-8 JSON strings as message bodies while mainframe consumers transform them downstream. MQ does not magically understand JSON—it stores octets like any message—but enterprise standards choose JSON for readability, schema validation, and tooling. Beginners double-encode JSON, lose Unicode characters, or ship giant payloads that exceed MAXMSGL. This tutorial explains JSON message structure in REST requests, persistence and descriptor fields, base64 for binary, schema and versioning, correlation ids in JSON properties, comparison to XML and fixed-length COBOL copybooks, poison message prevention, and performance considerations.
A typical REST put wraps content in an object with type, format, and message fields. String type carries plain JSON text; base64 type carries binary. Include persistence when events must survive queue manager restart. Priority and expiry fields map to MQMD concepts—set them explicitly for operational parity with MQI producers.
1234567{ "type": "string", "format": "json", "message": "{\"orderId\":\"A-9912\",\"amount\":42.50}", "persistence": "persistent", "priority": 5 }
| Practice | Benefit | Risk if skipped |
|---|---|---|
| Schema version field | Evolve producers safely | Consumer parse failures |
| Correlation id | End-to-end tracing | Cannot tie logs |
| UTF-8 explicit | International text | Mojibake characters |
| Size limits | Stay under MAXMSGL | Put fails 2190 |
Validate JSON Schema or OpenAPI definitions in CI/CD before deployment. Reject unknown required fields at the API gateway. Consumers should fail gracefully—route bad messages to DLQ after BOTHRESH backout rather than crash-looping. Document canonical examples per queue in Git for operations and partners.
MQI programs set MQMD.Format (for example MQFMT_STRING) and write buffers. REST JSON is a transport convenience; inside the data center you may convert JSON to COBOL copybook layout in an integration layer. Do not assume DISPLAY CHAR on the mainframe queue browser shows pretty JSON for all messages— encoding matters.
JMS and MQRFH2 carry properties for routing and filtering. Pure JSON payloads may embed metadata inside the document instead. Choose one pattern per integration and document it—mixing RFH2 properties with duplicate JSON fields confuses subscribers.
JSON is verbose versus binary. High-volume telemetry may use Avro, protobuf, or fixed binary on MQI while REST edge uses JSON for sparse control-plane traffic. Compress large payloads at application level only if both ends agree—MQ does not decompress automatically.
The mailbox (queue) holds a box (message bytes). JSON is writing the invoice on paper in a standard form everyone agreed to read—MQ still only sees the box.
You write your letter using words and punctuation everyone understands (JSON). The mail machine carries the paper—it does not check spelling unless you teach your friend who opens the letter to check spelling.
Publish JSON schema for one queue; reject one invalid test message in gateway.
Measure message size JSON vs compact binary for 10,000 sample records.
Add correlationId to JSON contract; trace one message REST to consumer log.
1. JSON in REST MQ is typically:
2. Invalid JSON at producer should be:
3. Binary over REST JSON often uses:
4. MQ stores JSON as: