Topic Hierarchies

Topic hierarchies are the deliberate design of how slash-separated levels are arranged before the first application publishes. IBM MQ does not mandate finance/payment/posted versus payment/finance/posted—the queue manager accepts any valid string—but enterprises that skip hierarchy planning drown in duplicate events, broken wildcards, and audit failures when nobody can list all subjects in a domain. Hierarchy design ties together topic trees, administrative topic objects, cluster parents, subscription patterns, and security prefixes. This tutorial gives beginners a practical framework: environment layer, domain layer, entity layer, event layer, optional region and version layers; naming rules; how hierarchy interacts with + and #; versioning and migration; anti-patterns; governance artifacts; and worked examples you can paste into a topic catalog workshop.

Recommended Level Model

Full example: prod/finance/payment/eu/posted. A subscription prod/finance/payment/# receives all payment events in production finance for all regions; prod/finance/+/eu/posted narrows to EU posted events only. Writing the hierarchy document before MQSC prevents developers inventing prod/finance/posted and prod/payments/finance/posted as competing paths.

Naming Rules That Survive Operations

• Use lowercase or consistent case—mixed case breaks matches on sensitive platforms.
• Use nouns for entities, past-tense verbs for events: order/created not order/createMessage.
• No spaces; avoid special characters beyond slash; no leading or trailing slashes.
• Keep segments short but meaningful—max roughly 32–64 characters per site policy.
• Never embed secrets, PAN, or personal data in topic strings—logs and DISPLAY echo them.

Hierarchy and Wildcards Together

When you add a region level, every subscription using + must gain a position or switch to #. Migration from prod/retail/order/created to prod/retail/uk/order/created breaks prod/retail/+/created because two variable levels now exist where + allowed one. Plan hierarchy depth before shipping first consumers. Document which integration partners may use # at entity level versus exact leaf only—broad # at prod/retail/# can double message volume overnight when a new high-frequency sensor topic appears under retail.

1
2
3
4
5
6
7
* Catalog-aligned definitions
DEFINE TOPIC('PROD.RETAIL.ADMIN') TOPSTR('prod/retail') TOPTYPE(CLUS) +
  CLUSTER('CORP') DESCR('Production retail branch')
DEFINE TOPIC('PROD.RETAIL.ORDER.CREATED') +
  TOPSTR('prod/retail/order/created') TOPTYPE(LOCAL)
DEFINE SUB('ANALYTICS.RETAIL.ORDERS') TOPICSTR('prod/retail/order/#') +
  DESTQL('ANALYTICS.RETAIL.SUB') DESTQMGR('QM1')

Versioning in the Hierarchy

Schema changes—new JSON fields, renamed events—should add a version segment rather than reusing the same string with incompatible payload. prod/finance/payment/v1/posted and prod/finance/payment/v2/posted run in parallel; publishers cut over; subscribers migrate subscriptions; ALIAS topic objects can point legacy names to v2 during transition. Retire v1 only when DISPLAY SUB shows zero consumers and monitoring confirms zero publish rate for seven business days (your policy may differ).

Anti-Patterns

1. Flat codes: EVT000412 with no domain—operations cannot grep logs by business area.
2. Embedding queue names in topics: Q.PAYMENT.IN.EVENT—confuses pub/sub with point-to-point.
3. Per-developer prefixes: steve/test/—pollutes shared tree; use personal queue managers instead.
4. Depth explosion: ten levels for simple status—wildcard maintenance becomes error-prone.
5. Duplicate synonyms: order/placed and order/created for same business fact without documentation.

Governance Artifacts

Maintain a topic catalog spreadsheet or internal portal: level definitions, owning team, sample payload, retention policy, allowed publishers, cluster name, PUBSCOPE, example subscription. Link each row to DEFINE TOPIC object name. Change control requires architecture review when adding domain roots or new environment prefixes. Quarterly DISPLAY TOPIC(*) diff against catalog catches drift.

Explainer: Postal Address Format

Hierarchy is country / city / street / building / apartment. Everyone uses the same order so mail sorts correctly. Random address formats mean mail arrives late or to the wrong apartment—even if each line “looks fine” alone.

Explain Like I'm Five: Topic Hierarchies

Topic hierarchy is agreeing how to write addresses so everyone puts country, then city, then street in the same order. If one friend writes street-first and another country-last, the mail room gets confused.

Practice Exercises

Exercise 1

Design hierarchy for healthcare claims with environment, domain, entity, event, region.

Exercise 2

Given migration adding region level, rewrite subscription prod/logistics/+/delivered.

Exercise 3

Write five naming rules for your organization topic catalog.

Frequently Asked Questions

Test Your Knowledge