--- type: "resource" title: "MessageDefinition" resource: "MessageDefinition" --- # MessageDefinition ## Introduction ## Scope and Usage Implementers should be familiar with the messaging concepts and descriptions found in [Messaging using FHIR Resources](messaging) before working with this resource. ## StructureDefinition ### Elements (Simplified) - **[MessageDefinition](/messagedefinition-definitions#MessageDefinition)** [0..*]: - A resource that defines a type of message that can be exchanged between systems - **[MessageDefinition.url](/messagedefinition-definitions#MessageDefinition.url)** [0..1]: [uri](/uri) The cannonical URL for a given MessageDefinition - **[MessageDefinition.identifier](/messagedefinition-definitions#MessageDefinition.identifier)** [0..*]: [Identifier](/Identifier) Business Identifier for a given MessageDefinition - **[MessageDefinition.version](/messagedefinition-definitions#MessageDefinition.version)** [0..1]: [string](/string) Business version of the message definition - **[MessageDefinition.versionAlgorithm[x]](/messagedefinition-definitions#MessageDefinition.versionAlgorithm%5Bx%5D)** [0..1]: [string](/string), [Coding](/Coding) extensible:[version-algorithm](/valueset-version-algorithm) How to compare versions - **[MessageDefinition.name](/messagedefinition-definitions#MessageDefinition.name)** [0..1]: [string](/string) Name for this message definition (computer friendly) - **[MessageDefinition.title](/messagedefinition-definitions#MessageDefinition.title)** [0..1]: [string](/string) Name for this message definition (human friendly) - **[MessageDefinition.replaces](/messagedefinition-definitions#MessageDefinition.replaces)** [0..*]: [canonical](/canonical) Takes the place of - **[MessageDefinition.status](/messagedefinition-definitions#MessageDefinition.status)** [1..1]: [code](/code) required:[publication-status](/valueset-publication-status) draft | active | retired | unknown - **[MessageDefinition.experimental](/messagedefinition-definitions#MessageDefinition.experimental)** [0..1]: [boolean](/boolean) For testing only - never for real usage - **[MessageDefinition.date](/messagedefinition-definitions#MessageDefinition.date)** [1..1]: [dateTime](/dateTime) Date last changed - **[MessageDefinition.publisher](/messagedefinition-definitions#MessageDefinition.publisher)** [0..1]: [string](/string) Name of the publisher/steward (organization or individual) - **[MessageDefinition.contact](/messagedefinition-definitions#MessageDefinition.contact)** [0..*]: [ContactDetail](/ContactDetail) Contact details for the publisher - **[MessageDefinition.description](/messagedefinition-definitions#MessageDefinition.description)** [0..1]: [markdown](/markdown) Natural language description of the message definition - **[MessageDefinition.useContext](/messagedefinition-definitions#MessageDefinition.useContext)** [0..*]: [UsageContext](/UsageContext) The context that the content is intended to support - **[MessageDefinition.jurisdiction](/messagedefinition-definitions#MessageDefinition.jurisdiction)** [0..*]: [CodeableConcept](/CodeableConcept) extensible:[jurisdiction](/valueset-jurisdiction) Jurisdiction of the authority that maintains the message definition (if applicable) - **[MessageDefinition.purpose](/messagedefinition-definitions#MessageDefinition.purpose)** [0..1]: [markdown](/markdown) Why this message definition is defined - **[MessageDefinition.copyright](/messagedefinition-definitions#MessageDefinition.copyright)** [0..1]: [markdown](/markdown) Notice about intellectual property ownership, can include restrictions on use - **[MessageDefinition.copyrightLabel](/messagedefinition-definitions#MessageDefinition.copyrightLabel)** [0..1]: [string](/string) Copyright holder and year(s) - **[MessageDefinition.base](/messagedefinition-definitions#MessageDefinition.base)** [0..1]: [canonical](/canonical) Definition this one is based on - **[MessageDefinition.parent](/messagedefinition-definitions#MessageDefinition.parent)** [0..*]: [canonical](/canonical) Protocol/workflow this is part of - **[MessageDefinition.event[x]](/messagedefinition-definitions#MessageDefinition.event%5Bx%5D)** [1..1]: [Coding](/Coding), [uri](/uri) example:[message-events](/valueset-message-events) Event code or link to the EventDefinition - **[MessageDefinition.category](/messagedefinition-definitions#MessageDefinition.category)** [0..1]: [code](/code) required:[message-significance-category](/valueset-message-significance-category) consequence | currency | notification - **[MessageDefinition.focus](/messagedefinition-definitions#MessageDefinition.focus)** [0..*]: [BackboneElement](/BackboneElement) Resource(s) that are the subject of the event - **[MessageDefinition.focus.code](/messagedefinition-definitions#MessageDefinition.focus.code)** [1..1]: [code](/code) required:[resource-types](/valueset-resource-types) Type of resource - **[MessageDefinition.focus.profile](/messagedefinition-definitions#MessageDefinition.focus.profile)** [0..1]: [canonical](/canonical) Profile that must be adhered to by focus - **[MessageDefinition.focus.min](/messagedefinition-definitions#MessageDefinition.focus.min)** [1..1]: [unsignedInt](/unsignedInt) Minimum number of focuses of this type - **[MessageDefinition.focus.max](/messagedefinition-definitions#MessageDefinition.focus.max)** [0..1]: [string](/string) Maximum number of focuses of this type - **[MessageDefinition.responseRequired](/messagedefinition-definitions#MessageDefinition.responseRequired)** [0..1]: [code](/code) required:[messageheader-response-request](/valueset-messageheader-response-request) always | on-error | never | on-success - **[MessageDefinition.allowedResponse](/messagedefinition-definitions#MessageDefinition.allowedResponse)** [0..*]: [BackboneElement](/BackboneElement) Responses to this message - **[MessageDefinition.allowedResponse.message](/messagedefinition-definitions#MessageDefinition.allowedResponse.message)** [1..1]: [canonical](/canonical) Reference to allowed message definition response - **[MessageDefinition.allowedResponse.situation](/messagedefinition-definitions#MessageDefinition.allowedResponse.situation)** [0..1]: [markdown](/markdown) When should this response be used ## Mappings - [MessageDefinition Mappings](/messagedefinition-mappings) — 31 mapping entries ## Resource Packs ### list-MessageDefinition-packs.xml ```xml ``` ## Search Parameters - [category](/messagedefinition-search#category) — **token** — The behavior associated with the message — `MessageDefinition.category` - [context](/messagedefinition-search#context) — **token** — A use context assigned to the message definition — `(MessageDefinition.useContext.value.ofType(CodeableConcept))` - [context-quantity](/messagedefinition-search#context-quantity) — **quantity** — A quantity- or range-valued use context assigned to the message definition — `(MessageDefinition.useContext.value.ofType(Quantity)) | (MessageDefinition.useContext.value.ofType(Range))` - [context-type](/messagedefinition-search#context-type) — **token** — A type of use context assigned to the message definition — `MessageDefinition.useContext.code` - [context-type-quantity](/messagedefinition-search#context-type-quantity) — **composite** — A use context type and quantity- or range-based value assigned to the message definition — `MessageDefinition.useContext` - [context-type-value](/messagedefinition-search#context-type-value) — **composite** — A use context type and value assigned to the message definition — `MessageDefinition.useContext` - [date](/messagedefinition-search#date) — **date** — The message definition publication date — `MessageDefinition.date` - [description](/messagedefinition-search#description) — **string** — The description of the message definition — `MessageDefinition.description` - [event](/messagedefinition-search#event) — **token** — The event that triggers the message or link to the event definition. — `MessageDefinition.event.ofType(Coding)` - [focus](/messagedefinition-search#focus) — **token** — A resource that is a permitted focus of the message — `MessageDefinition.focus.code` - [identifier](/messagedefinition-search#identifier) — **token** — External identifier for the message definition — `MessageDefinition.identifier` - [jurisdiction](/messagedefinition-search#jurisdiction) — **token** — Jurisdiction of the authority that maintains the the message definition — `MessageDefinition.jurisdiction` - [name](/messagedefinition-search#name) — **string** — Computationally friendly name of the message definition — `MessageDefinition.name` - [publisher](/messagedefinition-search#publisher) — **string** — Name of the publisher of the message definition — `MessageDefinition.publisher` - [status](/messagedefinition-search#status) — **token** — The current status of the message definition — `MessageDefinition.status` - [title](/messagedefinition-search#title) — **string** — The human-friendly name of the message definition — `MessageDefinition.title` - [url](/messagedefinition-search#url) — **uri** — The uri that identifies the message definition — `MessageDefinition.url` - [version](/messagedefinition-search#version) — **token** — The business version of the message definition — `MessageDefinition.version` - [experimental](/messagedefinition-search#experimental) — **token** — Whether the MessageDefinition is experimental — `MessageDefinition.experimental` [Full Search Parameters](/messagedefinition-search) ## Examples - [example](/messagedefinition-example-example) — messagedefinition-example — A typical message definition - [messagedefinition-example](/messagedefinition-example-messagedefinition-example) — messagedefinition-example - [messagedefinition-examples-header](/messagedefinition-example-messagedefinition-examples-header) — messagedefinition-examples-header - [patient-link-notification](/messagedefinition-example-patient-link-notification) — messagedefinition-patient-link-notification — An example of a patient link notification - [patient-link-response](/messagedefinition-example-patient-link-response) — messagedefinition-patient-link-response — An example of a patient link response [Full Examples](/messagedefinition-examples) ## Mapping Exceptions ### messagedefinition-definition-mapping-exceptions.xml ### Divergent Elements - **Definition.url** → **MessageDefinition.url** - shortUnmatched | reason=Unknown | pattern=Canonical identifier for this message definition, represented as an absolute URI (globally unique) | resource=The cannonical URL for a given MessageDefinition - definitionUnmatched | reason=Unknown | pattern=An absolute URI that is used to identify this message definition when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which an authoritative instance of this message definition is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the message definition is stored on different servers. | resource=The business identifier that is used to reference the MessageDefinition and *is* expected to be consistent from server to server. - commentsUnmatched | reason=Unknown | pattern=Can be a `urn:uuid:` or a `urn:oid:` but real `http/s:` addresses are preferred. Multiple instances may share the same URL if they have a distinct version. The determination of when to create a new version of a resource (same url, new version) vs. defining a new artifact is up to the author. Considerations for making this decision are found in [Technical and Business Versions](resource.html#versions). In some cases, the resource can no longer be found at the stated url, but the url itself cannot change. Implementations can use the [meta.source](resource.html#meta) element to indicate where the current master source of the resource can be found. | resource=Can be a urn:uuid: or a urn:oid: but real http: addresses are preferred. Multiple instances may share the same URL if they have a distinct version. The determination of when to create a new version of a resource (same url, new version) vs. defining a new artifact is up to the author. Considerations for making this decision are found in [Technical and Business Versions](resource.html#versions). In some cases, the resource can no longer be found at the stated url, but the url itself cannot change. Implementations can use the [meta.source](resource.html#meta) element to indicate where the current master source of the resource can be found. - **Definition.identifier** → **MessageDefinition.identifier** - shortUnmatched | reason=Unknown | pattern=Business identifier for message definition | resource=Business Identifier for a given MessageDefinition - commentsUnmatched | reason=Unknown | pattern=Typically, this is used for identifiers that can go in an HL7 V3 II (instance identifier) data type, and can then identify this message definition outside of FHIR, where it is not possible to use the logical URI. - requirementsUnmatched | reason=Unknown | pattern=Allows externally provided and/or usable business identifiers to be easily associated with the message definition. | resource=Allows externally provided and/or usable business identifiers to be easily associated with the module. - **Definition.version** → **MessageDefinition.version** - commentsUnmatched | reason=Unknown | pattern=There may be different message definitions that have the same url but different versions. The version can be appended to the url in a reference to allow a reference to a particular business version of the message definition with the format. The version SHOULD NOT contain a '#' - see [Business Version](resource.html#bv-format). | resource=There may be different message definition instances that have the same identifier but different versions. The version can be appended to the url in a reference to allow a reference to a particular business version of the message definition with the format [url]|[version]. The version SHOULD NOT contain a '#' - see [Business Version](resource.html#bv-format). - **Definition.name** → **MessageDefinition.name** - commentsUnmatched | reason=Unknown | pattern=The name is not expected to be globally unique. The name should be a simple alphanumeric type no-whitespace name to ensure that it is machine-processing friendly. | resource=The name is not expected to be globally unique. The name should be a simple alphanumeric type name to ensure that it is machine-processing friendly. - requirementsUnmatched | reason=Unknown | pattern=Supports code generation. | resource=Support human navigation and code generation. - **Definition.status** → **MessageDefinition.status** - definitionUnmatched | reason=Unknown | pattern=The current state of this message definition. | resource=The status of this message definition. Enables tracking the life-cycle of the content. - commentsUnmatched | reason=Unknown | pattern=A nominal state-transition diagram can be found in the] documentation Unknown does not represent 'other' - one of the defined statuses must apply. Unknown is used when the authoring system is not sure what the current status is. | resource=Allows filtering of message definitions that are appropriate for use versus not. See guidance around (not) making local changes to elements [here](canonicalresource.html#localization). - requirementsUnmatched | reason=Unknown | pattern=Enables tracking the lifecycle of the content and filtering of message definitions that are appropriate for use versus not. - **Definition.date** → **MessageDefinition.date** - **Definition.description** → **MessageDefinition.description** - commentsUnmatched | reason=Unknown | pattern=This description can be used to capture details such as comments about misuse, instructions for clinical use and interpretation, literature references, examples from the paper world, etc. It is not a rendering of the message definition as conveyed in the 'text' field of the resource itself. This item SHOULD be populated unless the information is available from context. | resource=This description can be used to capture details such as comments about misuse, instructions for clinical use and interpretation, literature references, examples from the paper world, etc. It is not a rendering of the message definition as conveyed in the 'text' field of the resource itself. This item SHOULD be populated unless the information is available from context (e.g. the language of the message definition is presumed to be the predominant language in the place the message definition was created). - **Definition.useContext** → **MessageDefinition.useContext** - definitionUnmatched | reason=Unknown | pattern=The content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate message definitions. | resource=The content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate message definition instances. - commentsUnmatched | reason=Unknown | pattern=When multiple useContexts are specified, there is no expectation that all or even any of the contexts apply. | resource=When multiple useContexts are specified, there is no expectation that all or any of the contexts apply. - **Definition.jurisdiction** → **MessageDefinition.jurisdiction** - shortUnmatched | reason=Unknown | pattern=Intended jurisdiction for message definition (if applicable) | resource=Jurisdiction of the authority that maintains the message definition (if applicable) - definitionUnmatched | reason=Unknown | pattern=A legal or geographic region in which the message definition is intended to be used. | resource=A legal or geographic region in which the authority that maintains the resource is operating. In general, the jurisdiction is also found in the useContext. The useContext may reference additional jurisdictions because the defining jurisdiction does not necessarily limit the jurisdictions of use. - commentsUnmatched | reason=Unknown | pattern=It may be possible for the message definition to be used in jurisdictions other than those for which it was originally designed or intended DEPRECATION NOTE: For consistency, implementations are encouraged to migrate to using the new 'jurisdiction' code in the useContext element. (I.e. useContext.code indicating http://terminology.hl7.org/CodeSystem/usage-context-type#jurisdiction and useContext.valueCodeableConcept indicating the jurisdiction.). | resource=It may be possible for the message definition to be used in jurisdictions other than those for which it was originally designed or intended. DEPRECATION NOTE: For consistency, implementations are encouraged to migrate to using the new 'jurisdiction' code in the useContext element. (I.e. useContext.code indicating http://terminology.hl7.org/CodeSystem/usage-context-type#jurisdiction and useContext.valueCodeableConcept indicating the jurisdiction.) - **Definition.purpose** → **MessageDefinition.purpose** - summary | reason=Unknown | pattern=false - **Definition.copyright** → **MessageDefinition.copyright** - requirementsUnmatched | reason=Unknown | pattern=Consumers of the message definition must be able to determine any legal restrictions on the use of the artifact and/or its content. | resource=Consumers must be able to determine any legal restrictions on the use of the message definition and/or its content. ### Unmapped Elements - **Definition.derivedFromCanonical** — Unknown - **Definition.approvalDate** — Unknown - **Definition.copyrightLabel** — Unknown - **Definition.effectivePeriod** — Unknown - **Definition.product** — Unknown - **Definition.code** — Unknown - **Definition.lastReviewDate** — Unknown - **Definition.subject** — Unknown - **Definition.derivedFromUri** — Unknown - **Definition.versionAlgorithm** — Unknown - **Definition.performerType** — Unknown - **Definition.partOf** — Unknown - **Definition.topic** — Unknown ### messagedefinition-fivews-mapping-exceptions.xml ### Unmapped Elements - **FiveWs.what** — Unknown - **FiveWs.author** — Unknown - **FiveWs.actor** — Unknown - **FiveWs.cause** — Unknown - **FiveWs.where** — Unknown - **FiveWs.context** — Unknown - **FiveWs.init** — Unknown - **FiveWs.source** — Unknown - **FiveWs.who** — Unknown - **FiveWs.grade** — Unknown - **FiveWs.planned** — Unknown - **FiveWs.done** — Unknown - **FiveWs.subject** — Unknown