MessageDefinition — Defining a messaging event

What ADT_A01 is to HL7 v2, MessageDefinition is to FHIR messaging: the formal definition of an event, the expected content, and the allowed response.

Purpose

MessageDefinition is the metadata describing a FHIR messaging event: which event code (the eventCoding), which resources are expected as focus, which profiles they must conform to, which responses are allowed.

Where HL7 v2 published abstract structures (ADT_A01, ORM_O01) in the standard, FHIR encodes the same as a resource: one MessageDefinition per business event, packaged in an Implementation Guide.

Key fields

JSON example

MessageDefinition Patient Link Notification: notifies the merge or link between two patients (a typical identity-vigilance case):

{
  "resourceType": "MessageDefinition",
  "id": "patient-link",
  "url": "http://hl7.org/fhir/MessageDefinition/patient-link",
  "version": "5.0.0",
  "name": "PatientLinkNotification",
  "title": "Patient Link Notification",
  "status": "draft",
  "experimental": true,
  "date": "2026-05-14",
  "publisher": "HL7 (FHIR Project)",
  "description": "Notification of a link between two patients (merge, duplicate).",
  "eventCoding": {
    "system": "http://hl7.org/fhir/message-events",
    "code": "patient-link"
  },
  "category": "notification",
  "focus": [{
    "code": "Patient",
    "profile": "http://hl7.org/fhir/StructureDefinition/Patient",
    "min": 2,
    "max": "2"
  }],
  "responseRequired": "always",
  "allowedResponse": [{
    "message": "http://hl7.org/fhir/MessageDefinition/patient-link-response"
  }]
}

Common pitfalls

• event[x] inconsistent with MessageHeader.event[x] — the code in MessageHeader MUST match the cited MessageDefinition.
• Poorly thought focus cardinality — for an event like patient-link, focus.min=2 requires two Patients; for an admit, just one.
• Required response without allowedResponse — declaring responseRequired=always without listing a response MessageDefinition makes the IG unusable.
• Confusing MessageDefinition vs OperationDefinition — the former describes an asynchronous event (Bundle push), the latter a synchronous operation ($xxx).

Related resources

• MessageHeader — references this MessageDefinition via definition.
• GraphDefinition — describes the complete expected resource graph.
• ImplementationGuide — package for IHE / national MessageDefinitions.
• OperationDefinition — synchronous alternative.