--- type: "resource" title: "StructureMap" resource: "StructureMap" --- # StructureMap ## Introduction ## Scope and Usage The _StructureMap_ resource defines a detailed set of rules that describe how one [Structure](structuredefinition) is related to another and provides sufficient detail to allow for automated conversion of instances. The intention of the structure map resource is to allow a specialist in formats and interoperability to specify the full relationships between two structures (e.g. a CDA document and a set of FHIR resources), and then many different systems - both testing and production clinical systems - can leverage that to automatically transform from one format to the other. Maps are unidirectional: they map from the source structure to the target structure, and no reverse map is implied. Even if the mapping is simple, and loss-less, it cannot be assumed that there are no conditions that might additionally apply in the reverse direction. The mapping language, along with a concrete syntax, is defined in detail in [the FHIR Mapping Language](mapping-language). The StructureMap resource represents the abstract syntax, and the concrete syntax is the recommended narrative representation for a StructureMap. See also the [Tutorial](mapping-tutorial). ## Boundaries and Relationships Note that many mappings between models only establish conceptual equivalence between the structures. These models are useful because they quickly convey how the structures are related to humans, whereas more maps with sufficient detail to support instance transformation are necessarily full of fine detail that can obscure the conceptual relationships. The [ConceptMap](conceptmap) resource is suitable for representing high level relationships between models, while this _StructureMap_ resource is intended to describe the full details that need to be known in order to transform an instance of data from one structure to another. The _StructureMap_ resource assumes that both the source and the target models are fully defined using [StructureDefinition](structuredefinition) resources - either resources, or logical models, and is described accordingly. However, there is no direct relationship between the mapping language contained in the StructureMap resource, and the existence of the appropriate structure definitions, so that this mapping language could be used to define a map from an HL7 V2 message to a CDA document. Note, that various implementation contexts may introduce a direct relationship (e.g. see \[op to defined\]). It's possible to apply the mapping language to structures that do not even have (or cannot have) formally defined types, although the type-related parts of the mapping language cannot be used in these cases. The Mapping Language and the `StructureMap` resource are built on top of [FHIRPath](fhirpath), and a FHIRPath implementation is required in order to execute a StructureMap. ## Background and Context Each structure map contains, in addition to the standard metadata that all conformance resources contain, the following information: - A list of the structure definitions referenced by the map - A list of other structure maps that the map uses - One or more groups of rules that describe how content in the source is transformed to content in the target Each group of rules defines a set of input and output variables that must be passed when the group is invoked in a particular context. When a group is invoked, all the rules in the group are checked to see whether they apply. Each rule may have some or all of the following properties: - A name - used as the identity in internal references, and traces - Contexts in both source and target models that define where the rule applies - A set of source elements that provide data to be mapped - Conditions that specify if the rule is to apply - A set of target elements that will be created - Transform rules that describe how raw data is converted from the source format to the target format (e.g. string manipulation) - Flags for how instances that can repeat are handled - Additional rules that apply to the newly created elements (e.g. new contexts) The mapping language is entirely declarative; there is no imperative or procedural aspects to the definitions. ## StructureDefinition ### Elements (Simplified) - **[StructureMap](/structuremap-definitions#StructureMap)** [0..*]: - A Map of relationships between 2 structures that can be used to transform data - **[StructureMap.url](/structuremap-definitions#StructureMap.url)** [1..1]: [uri](/uri) Canonical identifier for this structure map, represented as a URI (globally unique) - **[StructureMap.identifier](/structuremap-definitions#StructureMap.identifier)** [0..*]: [Identifier](/Identifier) Additional identifier for the structure map - **[StructureMap.version](/structuremap-definitions#StructureMap.version)** [0..1]: [string](/string) Business version of the structure map - **[StructureMap.versionAlgorithm[x]](/structuremap-definitions#StructureMap.versionAlgorithm%5Bx%5D)** [0..1]: [string](/string), [Coding](/Coding) extensible:[version-algorithm](/valueset-version-algorithm) How to compare versions - **[StructureMap.name](/structuremap-definitions#StructureMap.name)** [1..1]: [string](/string) Name for this structure map (computer friendly) - **[StructureMap.title](/structuremap-definitions#StructureMap.title)** [0..1]: [string](/string) Name for this structure map (human friendly) - **[StructureMap.status](/structuremap-definitions#StructureMap.status)** [1..1]: [code](/code) required:[publication-status](/valueset-publication-status) draft | active | retired | unknown - **[StructureMap.experimental](/structuremap-definitions#StructureMap.experimental)** [0..1]: [boolean](/boolean) For testing only - never for real usage - **[StructureMap.date](/structuremap-definitions#StructureMap.date)** [0..1]: [dateTime](/dateTime) Date last changed - **[StructureMap.publisher](/structuremap-definitions#StructureMap.publisher)** [0..1]: [string](/string) Name of the publisher/steward (organization or individual) - **[StructureMap.contact](/structuremap-definitions#StructureMap.contact)** [0..*]: [ContactDetail](/ContactDetail) Contact details for the publisher - **[StructureMap.description](/structuremap-definitions#StructureMap.description)** [0..1]: [markdown](/markdown) Natural language description of the structure map - **[StructureMap.useContext](/structuremap-definitions#StructureMap.useContext)** [0..*]: [UsageContext](/UsageContext) The context that the content is intended to support - **[StructureMap.jurisdiction](/structuremap-definitions#StructureMap.jurisdiction)** [0..*]: [CodeableConcept](/CodeableConcept) extensible:[jurisdiction](/valueset-jurisdiction) Jurisdiction of the authority that maintains the structure map (if applicable) - **[StructureMap.purpose](/structuremap-definitions#StructureMap.purpose)** [0..1]: [markdown](/markdown) Why this structure map is defined - **[StructureMap.copyright](/structuremap-definitions#StructureMap.copyright)** [0..1]: [markdown](/markdown) Notice about intellectual property ownership, can include restrictions on use - **[StructureMap.copyrightLabel](/structuremap-definitions#StructureMap.copyrightLabel)** [0..1]: [string](/string) Copyright holder and year(s) - **[StructureMap.structure](/structuremap-definitions#StructureMap.structure)** [0..*]: [BackboneElement](/BackboneElement) Structure Definition used by this map - **[StructureMap.structure.url](/structuremap-definitions#StructureMap.structure.url)** [1..1]: [canonical](/canonical) Canonical reference to structure definition - **[StructureMap.structure.mode](/structuremap-definitions#StructureMap.structure.mode)** [1..1]: [code](/code) required:[map-model-mode](/valueset-map-model-mode) source | queried | target | produced - **[StructureMap.structure.alias](/structuremap-definitions#StructureMap.structure.alias)** [0..1]: [string](/string) Name for type in this map - **[StructureMap.structure.documentation](/structuremap-definitions#StructureMap.structure.documentation)** [0..1]: [string](/string) Documentation on use of structure - **[StructureMap.import](/structuremap-definitions#StructureMap.import)** [0..*]: [canonical](/canonical) Other maps used by this map (canonical URLs) - **[StructureMap.const](/structuremap-definitions#StructureMap.const)** [0..*]: [BackboneElement](/BackboneElement) Definition of the constant value used in the map rules - **[StructureMap.const.name](/structuremap-definitions#StructureMap.const.name)** [0..1]: [id](/id) Constant name - **[StructureMap.const.value](/structuremap-definitions#StructureMap.const.value)** [0..1]: [string](/string) FHIRPath exression - value of the constant - **[StructureMap.group](/structuremap-definitions#StructureMap.group)** [1..*]: [BackboneElement](/BackboneElement) Named sections for reader convenience - **[StructureMap.group.name](/structuremap-definitions#StructureMap.group.name)** [1..1]: [id](/id) Human-readable label - **[StructureMap.group.extends](/structuremap-definitions#StructureMap.group.extends)** [0..1]: [id](/id) Another group that this group adds rules to - **[StructureMap.group.typeMode](/structuremap-definitions#StructureMap.group.typeMode)** [0..1]: [code](/code) required:[map-group-type-mode](/valueset-map-group-type-mode) types | type-and-types - **[StructureMap.group.documentation](/structuremap-definitions#StructureMap.group.documentation)** [0..1]: [string](/string) Additional description/explanation for group - **[StructureMap.group.input](/structuremap-definitions#StructureMap.group.input)** [1..*]: [BackboneElement](/BackboneElement) Named instance provided when invoking the map - **[StructureMap.group.input.name](/structuremap-definitions#StructureMap.group.input.name)** [1..1]: [id](/id) Name for this instance of data - **[StructureMap.group.input.type](/structuremap-definitions#StructureMap.group.input.type)** [0..1]: [string](/string) Type for this instance of data - **[StructureMap.group.input.mode](/structuremap-definitions#StructureMap.group.input.mode)** [1..1]: [code](/code) required:[map-input-mode](/valueset-map-input-mode) source | target - **[StructureMap.group.input.documentation](/structuremap-definitions#StructureMap.group.input.documentation)** [0..1]: [string](/string) Documentation for this instance of data - **[StructureMap.group.rule](/structuremap-definitions#StructureMap.group.rule)** [0..*]: [BackboneElement](/BackboneElement) Transform Rule from source to target - **[StructureMap.group.rule.name](/structuremap-definitions#StructureMap.group.rule.name)** [0..1]: [id](/id) Name of the rule for internal references - **[StructureMap.group.rule.source](/structuremap-definitions#StructureMap.group.rule.source)** [1..*]: [BackboneElement](/BackboneElement) Source inputs to the mapping - **[StructureMap.group.rule.source.context](/structuremap-definitions#StructureMap.group.rule.source.context)** [1..1]: [id](/id) Type or variable this rule applies to - **[StructureMap.group.rule.source.min](/structuremap-definitions#StructureMap.group.rule.source.min)** [0..1]: [unsignedInt](/unsignedInt) Specified minimum cardinality - **[StructureMap.group.rule.source.max](/structuremap-definitions#StructureMap.group.rule.source.max)** [0..1]: [string](/string) Specified maximum cardinality (number or *) - **[StructureMap.group.rule.source.type](/structuremap-definitions#StructureMap.group.rule.source.type)** [0..1]: [string](/string) Rule only applies if source has this type - **[StructureMap.group.rule.source.defaultValue](/structuremap-definitions#StructureMap.group.rule.source.defaultValue)** [0..1]: [string](/string) Default value if no value exists - **[StructureMap.group.rule.source.element](/structuremap-definitions#StructureMap.group.rule.source.element)** [0..1]: [string](/string) Optional field for this source - **[StructureMap.group.rule.source.listMode](/structuremap-definitions#StructureMap.group.rule.source.listMode)** [0..1]: [code](/code) required:[map-source-list-mode](/valueset-map-source-list-mode) first | not_first | last | not_last | only_one - **[StructureMap.group.rule.source.variable](/structuremap-definitions#StructureMap.group.rule.source.variable)** [0..1]: [id](/id) Named context for field, if a field is specified - **[StructureMap.group.rule.source.condition](/structuremap-definitions#StructureMap.group.rule.source.condition)** [0..1]: [string](/string) FHIRPath expression - must be true or the rule does not apply - **[StructureMap.group.rule.source.check](/structuremap-definitions#StructureMap.group.rule.source.check)** [0..1]: [string](/string) FHIRPath expression - must be true or the mapping engine throws an error instead of completing - **[StructureMap.group.rule.source.logMessage](/structuremap-definitions#StructureMap.group.rule.source.logMessage)** [0..1]: [string](/string) Message to put in log if source exists (FHIRPath) - **[StructureMap.group.rule.target](/structuremap-definitions#StructureMap.group.rule.target)** [0..*]: [BackboneElement](/BackboneElement) Content to create because of this mapping rule - **[StructureMap.group.rule.target.context](/structuremap-definitions#StructureMap.group.rule.target.context)** [0..1]: [string](/string) Variable this rule applies to - **[StructureMap.group.rule.target.element](/structuremap-definitions#StructureMap.group.rule.target.element)** [0..1]: [string](/string) Field to create in the context - **[StructureMap.group.rule.target.variable](/structuremap-definitions#StructureMap.group.rule.target.variable)** [0..1]: [id](/id) Named context for field, if desired, and a field is specified - **[StructureMap.group.rule.target.listMode](/structuremap-definitions#StructureMap.group.rule.target.listMode)** [0..*]: [code](/code) required:[map-target-list-mode](/valueset-map-target-list-mode) first | share | last | single - **[StructureMap.group.rule.target.listRuleId](/structuremap-definitions#StructureMap.group.rule.target.listRuleId)** [0..1]: [id](/id) Internal rule reference for shared list items - **[StructureMap.group.rule.target.transform](/structuremap-definitions#StructureMap.group.rule.target.transform)** [0..1]: [code](/code) required:[map-transform](/valueset-map-transform) create | copy + - **[StructureMap.group.rule.target.parameter](/structuremap-definitions#StructureMap.group.rule.target.parameter)** [0..*]: [BackboneElement](/BackboneElement) Parameters to the transform - **[StructureMap.group.rule.target.parameter.value[x]](/structuremap-definitions#StructureMap.group.rule.target.parameter.value%5Bx%5D)** [1..1]: [id](/id), [string](/string), [boolean](/boolean), [integer](/integer), [decimal](/decimal), [date](/date), [time](/time), [dateTime](/dateTime) Parameter value - variable or literal - **[StructureMap.group.rule.rule](/structuremap-definitions#StructureMap.group.rule.rule)** [0..*]: - Rules contained in this rule - **[StructureMap.group.rule.dependent](/structuremap-definitions#StructureMap.group.rule.dependent)** [0..*]: [BackboneElement](/BackboneElement) Which other rules to apply in the context of this rule - **[StructureMap.group.rule.dependent.name](/structuremap-definitions#StructureMap.group.rule.dependent.name)** [1..1]: [id](/id) Name of a rule or group to apply - **[StructureMap.group.rule.dependent.parameter](/structuremap-definitions#StructureMap.group.rule.dependent.parameter)** [1..*]: - Parameter to pass to the rule or group - **[StructureMap.group.rule.documentation](/structuremap-definitions#StructureMap.group.rule.documentation)** [0..1]: [string](/string) Documentation for this instance of data ## Mappings - [StructureMap Mappings](/structuremap-mappings) — 13 mapping entries ## Operations - [transform](/structuremap-operation-transform) — Model Instance Transformation — The transform operation takes input content, applies a structure map transform, and then returns the output. [Full Operations](/structuremap-operations) ## Resource Packs ### list-StructureMap-packs.xml ```xml ``` ## Search Parameters - [context](/structuremap-search#context) — **token** — A use context assigned to the structure map — `(StructureMap.useContext.value.ofType(CodeableConcept))` - [context-quantity](/structuremap-search#context-quantity) — **quantity** — A quantity- or range-valued use context assigned to the structure map — `(StructureMap.useContext.value.ofType(Quantity)) | (StructureMap.useContext.value.ofType(Range))` - [context-type](/structuremap-search#context-type) — **token** — A type of use context assigned to the structure map — `StructureMap.useContext.code` - [context-type-quantity](/structuremap-search#context-type-quantity) — **composite** — A use context type and quantity- or range-based value assigned to the structure map — `StructureMap.useContext` - [context-type-value](/structuremap-search#context-type-value) — **composite** — A use context type and value assigned to the structure map — `StructureMap.useContext` - [date](/structuremap-search#date) — **date** — The structure map publication date — `StructureMap.date` - [description](/structuremap-search#description) — **string** — The description of the structure map — `StructureMap.description` - [identifier](/structuremap-search#identifier) — **token** — External identifier for the structure map — `StructureMap.identifier` - [jurisdiction](/structuremap-search#jurisdiction) — **token** — Jurisdiction of the authority that maintains the the structure map — `StructureMap.jurisdiction` - [name](/structuremap-search#name) — **string** — Computationally friendly name of the structure map — `StructureMap.name` - [publisher](/structuremap-search#publisher) — **string** — Name of the publisher of the structure map — `StructureMap.publisher` - [status](/structuremap-search#status) — **token** — The current status of the structure map — `StructureMap.status` - [title](/structuremap-search#title) — **string** — The human-friendly name of the structure map — `StructureMap.title` - [url](/structuremap-search#url) — **uri** — The uri that identifies the structure map — `StructureMap.url` - [version](/structuremap-search#version) — **token** — The business version of the structure map — `StructureMap.version` - [source](/structuremap-search#source) — **uri** — A source StructureDefinition for the map — `StructureMap.structure.where(mode = 'source').url` - [target](/structuremap-search#target) — **uri** — A target StructureDefinition for the map — `StructureMap.structure.where(mode = 'target').url` - [queried](/structuremap-search#queried) — **uri** — A queried StructureDefinition for the map — `StructureMap.structure.where(mode = 'queried').url` - [produced](/structuremap-search#produced) — **uri** — A produced StructureDefinition for the map — `StructureMap.structure.where(mode = 'produced').url` - [experimental](/structuremap-search#experimental) — **token** — Whether the StructureMap is experimental — `StructureMap.experimental` [Full Search Parameters](/structuremap-search) ## Examples - [example](/structuremap-example-example) — structuremap-example — Example - [structuremap-example](/structuremap-example-structuremap-example) — structuremap-example - [structuremap-examples-header](/structuremap-example-structuremap-examples-header) — structuremap-examples-header [Full Examples](/structuremap-examples) ## Mapping Exceptions ### structuremap-fivews-mapping-exceptions.xml ### Unmapped Elements - **FiveWs.what** — Not relevant for this resource - **FiveWs.author** — Not relevant for this resource - **FiveWs.actor** — Not relevant for this resource - **FiveWs.cause** — Not relevant for this resource - **FiveWs.where** — Not relevant for this resource - **FiveWs.context** — Unknown - **FiveWs.init** — Not relevant for this resource - **FiveWs.source** — Not relevant for this resource - **FiveWs.who** — Not relevant for this resource - **FiveWs.grade** — Not relevant for this resource - **FiveWs.planned** — Not relevant for this resource - **FiveWs.done** — Not relevant for this resource - **FiveWs.subject** — Not relevant for this resource