SMART Guidelines L3 SOP
1.0.0 - release International flag

This page is part of the SMART IG STARTER KIT (v1.0.0: Release) based on FHIR (HL7® FHIR® Standard) v5.0.0. This is the current published version. For a full list of available versions, see the Directory of published versions

Structure Maps

FHIR StructureMaps are machine-readable data transformation specifications . They are used in converting data from one format to another. For the SMART Guidelines, StructureMaps are used to convert data between QuestionnaireResponses and FHIR target profile instances. This is done in 2 steps:

  1. Extract a Questionnaire Response into a Logical Model instance
    This gets the data in a simple form that only depends on the data specification, and not on the profiles that are used
  2. Extract the Logical Model instance into the FHIR resource instances

This process is done by 3 StructureMaps:

  • The StructureMap from QuestionnaireResponse to logical model instance;
  • The StructureMap from logical model instance to Resource instance ;
  • A grouping map that combines the two maps above to enable a single transform operation.
Resource BundleResource InstanceLogical ModelProfileStrutureMapQResp → LMStrutureMapLM → InstanceStrutureMap(Group)QuestionnaireQuestionnaireResponseLM Instance(transform)(transform)                                                       

StructureMaps can be authored using the FHIR Mapping Language (see also tutorial).

Inputs

  • DAK Data Dictionary / L2 Logical Model
  • FHIR Profiles
  • Questionnaire
  • FHIR Artifacts catalog

Outputs

  • StructureMaps in input/resources/maps
  • Test Bundle that includes maps and all the dependencies

Activities

If a form is used, the L3 author should provide the mappings for extraction.

  • The StructureMap shall be saved as input/resources/maps/<id>.fml where id is the id of the map - not necessarily the name.
StrutureMapidentifier 1..*status 1..1name 1..1title 1..1description 1..1Data needs forstructure maps(seelegend)

These can come in the form of:

  • Observation extraction
  • Definition-based extraction
  • StructureMap extraction

Observation extraction

Observation-based extraction is described in the HL7 FHIR SDC (Structured Data Capture) specification. It is not part of the current scope of the SMART Guidelines, but may be used to obtain data.

Definition-based extraction

If this approach is used, the mapping is done by filling in the .definition element with the resource that is the target of the extraction - Patient, Observation, Encounter, etc.

StructureMap extraction

The following structuremaps are expected:

  • For Forms / Questionnaires
    • the data extraction map from Questionnaire to Logical Model instances
    • the data extraction map from Logical Model instances to FHIR resources
    • the combined data extraction map that includes the 2 maps above and can process the extraction from Questionnaire to FHIR Resources
  • StructureMaps may be difficult to implement and debug. It is important to compile the maps frequently while authoring, and check the output in the QA of the publisher.

Reusing StructureMaps:
StructureMaps may be reused. For example, modular questionnaires (like Patient demographic modules) - which would use common transformations.

Output Criteria / Definition of Done

  • Mappings should create valid StructureMaps - including the necessary metadata.
    • the map should be correctly compiled and validated by the publisher - no QA errors
    • optional metadata should be added according to the spec
      • group names shall not contain spaces
  • StructureMaps for extraction must be tested to successfully transform the artifacts (for example, in a Questionnaire, the StructureMaps ust be tested to successfully obtain the intended resources from the QuestionnaireResponse).
  • All mapped elements and groups should be tested
  • All the dependencies of the StructureMap shall be in the IG or dependencies - SDC, base profiles, logical models, etc.

Change tracking

As with all FHIR Conformance resources, change management is critical. Do not set the version element of StructureMaps defined in the SMART Guideline, the version element will be set by the publication process. See the versioning topic for more information on change management.

Tooling

Tool Usage Doc
Matchbox    
IG Publisher Convert FML files to StructureMaps  
     

Informative examples

SMART Guidelines - Immunizations (Measles): StructureMaps

Known issues and dependencies

  • Publisher doesn’t support metadata, so the StructureMaps show without description in the artifacts table
  • Matchbox doesn’t validate the metadata if it’s missing or if the StructureMap is not valid.