Open mHealth to FHIR - Local Development build (v0.0.0). See the Directory of published versions

OMH to FHIR Mapping

• Mapping OMH Schema Mappings to FHIR Elements
• Quick Start Mapping Guide
  • OMH Header Element to FHIR Element Mapping Table
  • Observation Template
  • observation_componentx Subtemplates
• Mapping Strategy
  • OMH Header Schema Mapping to FHIR elements
  • OMH Schema Mappings to FHIR Datatypes
  • OMH datapoint Schema Mappings to FHIR Resources
• Mapping Example

Mapping OMH Schema Mappings to FHIR Elements

Measurements such as steps or heart rate are modeled using OMH schemas. These models can be used to represent instance of the measurement “over the wire” in JSON. For example, using the step-count schema, a step count is represented as:

{
  "header": {
    "id": "243c773b-8936-407e-9c23-270d0ea49cc4",
    "creation_date_time": "2015-09-10T12:43:39.138-06:00",
    "acquisition_provenance": {
      "source_name": "Jawbone UP API",
      "modality": "sensed",
      "source_updated_date_time": "2015-09-10T18:43:39Z"
    },
    "schema_id": {
      "namespace": "omh",
      "name": "step_count",
      "version": "1.0"
    },
    "user_id": "306a1202-410d-11e8-842f-0ed5f89f718b"
  },
  "body": {
    "effective_time_frame": {
      "time_interval": {
        "start_date_time": "2015-08-06T05:11:09-07:00",
        "end_date_time": "2015-08-06T23:00:36-06:00"
      }
    },
    "step_count": 7939
  }
}

The OMH schema can be transformed into FHIR data models - more specifically “Logical Models” that allow for a more ‘FHR-like’ view of the schema and a way to computationally map between FHIR and omh. For example, this would allow the following transformation between the step count example and a FHIR representation using the Observation Resource:

Other mappings:

• Example Mapping for OMH Heart Rate Schema

Quick Start Mapping Guide

Formal FHIR Logical Models are included in this guide for mapping the models directly using a formal mapping syntax. However, the tables and templates below are provided to for quicks mappings an OMH schema instance to a FHIR quantitative Observation resource instance. These can be used to perform simple string substitution and simple concept mappings methods to generate FHIR Observations. An example python application using these tables and string templates is available

OMH Header Element to FHIR Element Mapping Table

Each OMH schema for a datapoint is composed of the ‘header’ and ‘body, This table is a map of the relatively static OMH heady element to the corresponding OMH to FHIR Observation Profile element. Each datapoint schema represents the body’s properties and will be covered individually.

Data Point Mapping Table

Each Datapoint is represented by the body properties and this table is a summarey of the OMH datapoint schema type as represented by the header.schema_id.name element to the corresponding FHIR Observation category and ‘code’ elements and default units for quantitative measures.

Data Point Component Mapping Table

Some Datapoints properties are represented by the FHIR Observation.component element in FHIR. This table summarizes these OMH datapoint schema properties and list the corresponding OMH propertied name in the Component Name column and its corresponding FHIR Observation component code and valuetype attributes. This table is used along with the OMH to FHIR concept mapping table to to populate the the Observation template below.

Observation Template

This FHIR Observation template is an instance view of the above mappings and can be populated with data from OMH schemas to create a FHIR Observation instance.

{
       "resourceType": "Observation",
       "id": {{server_assigned_resource_id}},  //note 1,2,6
       "meta": {
       "profile" : ["http://www.fhir.org/mfhir/StructureDefinition/omh_fhir_profile_quantitative_observation"]  // note 7
     },
     "extension" : [{
         "url" : {{observation_specimen_code_extension_url}},
         "valueCodeableConcept": {
         "coding": [
           {
             "system": {{observation_specimen_code_system}},
             "code": {{observation_specimen_code_code}},
             "display": {{observation_specimen_code_display}}
           }
         ],
         "text": {{observation_specimen_code_text}}
       }
    }],
       "identifier"  : [{
       "system" : "https://omh.org/shimmer/ids", //note 7
       "value" : {{header.id}} //note 3
       }],
       "status": "unknown",  //note 9
       "category": [  //note 4
         {
           "coding": [
             {
               "system": "http://hl7.org/fhir/observation-category",
               "code": {{observation_category_code}},
               "display": {{observation_category_display}}
             }
           ]
         }
       ],
       "code": {   //note 4
         "coding": [
           {
             "system": {{observation_code_system}},
             "code": {{observation_code_code}},
             "display": {{observation_code_display}}
           }
        ,{
          "system" : {{addl_observation_coding_system}}, //note 12
          "code" : {{addl_observation_coding_code}},
          "display" : {{addl_observation_coding_display}}
        }
         ]
       },
       "subject": {  //note 8
         "identifier" : {
       "system" : "https://omh.org/shimmer/patient_ids",
       "value" : {{header.user_id}}
     }
       },
       "effectiveDateTime" : {{body.effective_time_frame.date_time}},  //note 11
       "effectivePeriod" : {  //note 11
          "start" : {{body.effective_time_frame.time_interval.start_date_time}}, 
          "end" : {{body.effective_time_frame.time_interval.end_date_time}}
          }, 
       "issued": {{header.creation_date_time}},
       "valueQuantity" : {  //note 10
         "value" : {observation_value_quantity_value},
         "unit" : {{observation_value_quantity_unit}},
         "system" : {{observation_value_quantity_system}}, 
         "code" : {{observation_value_quantity_code}}
        },
        "comment" : {{body.user_notes}},
        "device" : {
        "extension" : [{
          "url" : "http://www.fhir.org/mfhir/StructureDefinition/omh_fhir_observation_device_modality",
          "valueCode" : {{header.acquisition_provenance.modality}}
        }],
        "display" : {{header.acquisition_provenance.source_name}}
        },
        "component": [{observation_componentx}]  //note 5
      }

observation_componentx Subtemplates

This FHIR Observation sub template is an instance view of the Observation component element derived from the OMH schema e and can be populated with data to create a FHIR Observation instance.

,"component" : [{
    "code" : { 
      "coding" : [{ 
        "system" :"http://www.fhir.org/guides/omhtofhir/omh_fhir_observation_codes",
        "code" : "{{observation_component_code_code}}", 
        "display" : "{{observation_component_code_display}}"
         }]
       },
    "valueCodeableConcept" : { 
      "coding" : [{ 
        "system" : "{{observation_component_value_codeableconcept_system}}", 
        "code" : "{{observation_component_value_codeableconcept_code}}", 
        "display" : "{{observation_component_value_codeableconcept_display}}"
        }],
        "text" : "{{observation_component_value_codeableconcept_text}}"
        },
       "valueQuantity" : {
         "value" : {{observation_component_value_quantity_value}},
         "unit" : "{{observation_component_value_quantity_unit}}",
         "system" : "{{observation_component_value_quantity_system}}", 
         "code" : "{{observation_component_value_quantity_code}}"
        }
     }

Notes on template usage:

1. Template variables are represented using the “{{}}” syntax
2. Note that when present, FHIR elements cannot be empty. Therefore, all ‘null’ values (i.e.,undefined, Null, None, or ‘’ values or empty json objects or lists) are removed from the resource after the OMH data is mapped to it.
3. Variable such as {{header.id}} represent OMH data elements in dot notation mapped directly from the header schema.
4. Variables in “snake case” are such as {{observation_category_code}} {{observation_code_code}} represent the corresponding dot notation columns in the OMH Data Point Mapping Table provided above(which are based on the OmhDataPoint.header.schema_id.name).
5. the variables {{observation-valuex}} (the actual result values), {{observation-effectivex}} (the actual times the measurements occurred ) and {{observation-componentx}} are subtemplates and are mapped from the body schema for each of the datapoints.
6. {{server_assigned_resource_id}} is a assigned by the server when the resource is created and is typically not mapped from the OMH schema instance.
7. The profile element is the FHIR profiles this resource claims will conform to when fully populated.
8. The namespaces, “https://omh.org/shimmer/ids” and “https://omh.org/shimmer/patient_ids” are use to assign a system to shimmer generated ids.
9. The status element is required in FHIR Observation and since omh schema don’t have status its values is hardcoded to ‘unknown’
10. The measurement value ( e.g., step-count) and units derived from the descriptive statistics schema and can be populated with data to create a FHIR Observation instance.
11. There is a choice of datetime or time period mappings over which the measurement occurred for the step count schema and can be populated with data it to create a FHIR Observation instance. Note that the empty values will be removed from the instance.
12. Additional codings are derived from the descriptive statistics schema using a compositional code consisting of the concatenation of the datapoint schema name with the descriptive statistic code in “spinal case” ( e.g step-count-maximum). If the descriptive statistics is absent the schema, there are no additional codings in the OMH to FHIR instance.

Mapping Strategy

In order to map the OMH schema to FHIR, the OMH Schemas are divided conceptually into several categories. The infrastructural schema model serves as a basic blueprint for creation of OMH schema and is not used in the mappings. The infrastructural data-point schema provide the basic framework upon which the data-points schemas are based and serves as the backbone for creation of the FHIR logical model. It is made up of a header property representing MedicationDispense information and a body property representing one of the omh schemas that represent a measurements i.e., ‘a data point’.

OMH Header Schema Mapping to FHIR elements

The OMH header schema represent data MedicationDispense and the properties in the header schema map to more than a single FHIR element. In addition, depending on the depth and level of detail required, there are multiple options to representing MedicationDispense including:

• ​MedicationDispenseresource
• meta.source element
• inline Resource elements

These options are summarized in the table below and described in detail in the data point logical model mappings.

The rest of the omh schemas represent either data points or more granular reusable elements or concepts that can be referenced within the data-point schemas. Each reusable omh schema are mapped primitive and complex datatypes as shown below. In addition some of these schemas enumerate values which are bound) to FHIR ValueSets. The reusable schemas are mapped directly to fhir artifacts as described below and these mapping replace the omh schema references when transforming an OMH data point schema into a FHIR Logical Model.

OMH Schema Mappings to FHIR Datatypes

In this table, the schemas representing primitive and complex data-types are mapped directly to the corresponding FHIR datatype. Listed in the FHIR ValueSet column the corresponding FHIR ValueSets and binding strength for the schemas that map to the FHIR code, an units values for the Quantity, and Range dataypes.

• ​Where a value is fixed such as for acceleration-unit-value-1.0.json, a fixed Pattern is associated with the schema which directly applied to the FHIR logical models when the schema is referenced.
• Where the unit value is an enumeration of units a FHIR ValueSet is associated with the schema.
• Both the patterns and ValueSets contain UCUM based units.
• For data point schemas that reference schemas associated with ValueSets (such as unit-value-1.0.json), the actual units and hence the patterns applied to the FHIR logical models van be further constrained by the data point schema themselves.

OMH datapoint Schema Mappings to FHIR Resources

Logical Models for each datapoint schema are mapped to a FHIR Logical Model before being mapped to the target FHIR resource profile as listed in the table below. The concept code for the measurement is in the description property of the schema are listed in the Observation.code column. For Schema that are mapped to Observation, this code is mapped to code in then Observation resource.:

Mapping Example

The transformation from the OMH data-point schema to the FHIR Logical models and from the FHIR Logical model to the FHIR resource is straightforward and demonstrated below.

Note:

• elements with a value of Null are not transmitted in FHIR
• some elements require a mapping to a codes using the translation tables in this Guide.

OMH Stepcount Datapoint instance

    {
      "header": {
        "id": "243c773b-8936-407e-9c23-270d0ea49cc4",
        "creation_date_time": "2015-09-10T12:43:39.138-06:00",
        "acquisition_MedicationDispense": {
          "source_name": "Jawbone UP API",
          "modality": "sensed",
          "source_updated_date_time": "2015-09-10T18:43:39Z"
        },
        "schema_id": {
          "namespace": "omh",
          "name": "step-count",
          "version": "1.0"
        },
        "user_id": "306a1202-410d-11e8-842f-0ed5f89f718b"
      },
      "body": {
        "effective_time_frame": {
          "time_interval": {
            "start_date_time": "2015-08-06T05:11:09-07:00",
            "end_date_time": "2015-08-06T23:00:36-06:00"
          }
        },
        "step_count": 7939
      }
    }

Converting this datapoint instance to dot notation representation here to show more clearly the mapping to the FHIR Observation Resource data elements

    O.header
        O.header.id = "243c773b-8936-407e-9c23-270d0ea49cc4"
        O.header.creation_date_time = "2015-09-10T12:43:39.138-06:00"
        O.header.acquisition_MedicationDispense"
          O.header.acquisition_MedicationDispense.source_name = "Jawbone UP API"
          O.header.acquisition_MedicationDispense.modality = "sensed"
          O.header.acquisition_MedicationDispense.source_updated_date_time = "2015-09-10T18:43:39Z"
        O.header.schema_id 
          O.header.schema_id.namespace  = "omh"
          O.header.schema_id.name =  "step-count"
          O.header.schema_id.version = "1.0"
        O.header.user_id = 306a1202-410d-11e8-842f-0ed5f89f718b"
      O.body 
        O.body.effective_time_frame 
          O.body.effective_time_frame.time_interval 
            O.body.effective_time_frame.time_interval.start_date_time = "2015-08-06T05:11:09-07:00"
            O.body.effective_time_frame.time_interval.end_date_time ="2015-08-06T23:00:36-06:00"
        O.body.step_count = 7939

**This OMH Schema instance maps to the FHIR Observation Resource directly as follows: ** (using the syntax %(foo) to represent the replacement variables in the resource) ‘’

        
        {
          "resourceType": "Observation",
        	"id": "steps-example //  this is a server assigned resource id",
          "meta": {
          "source" : "%(OmhDataPoint.header.acqusitionProvenance.sourceName)",
          "profile // Profiles this resource claims to conform to" : ["http://www.fhir.org/guides/omhtofhir/StructureDefinition/steps"]
        }
          "identifier  : [
          "system" : "https://omh.org/shimmer/ids // The namespace for the identifier value",
          "value" : "%(OmhDataPoint.header.Id)",
          }],
          "status": "unknown // this is required in fhir - omh schema don't have status",
        	"category // optional category field to indicate is an activity vs say a lab result": [  
        		{
        			"coding": [
        				{
        					"system": "http://hl7.org/fhir/observation-category",
        					"code": "activity",
        					"display": "Activity"
        				}
        			]
        		}
        	],
        	"code // code mapping from OmhDataPoint.header.schema_id.name see mapping table in IG": {
        		"coding": [
              {
        				"system": "http://loinc.org",
        				"code": "55423-8",
        				"display": "Number of steps in unspecified time Pedometer"
        			}
        		],
        		"text": "Step count"
        	},
        	"subject": {
        		"identifier" : {
          "system" : "https://omh.org/shimmer/patient_ids // The namespace for the identifier value",
          "value" : "%(OmhDataPoint.header.user_id)",
        },
        	},
        	"effectivePeriod // mapped from OmhDataPoint.body.effectiveTimeFrame":
          "start" : "%(OmhDataPoint.body.effective_time_frame.time_interval.start_date_time)",
          "end" : "%(OmhDataPoint.body.effective_time_frame.time_interval.end_date_time)"
            }
        	"issued": "%(OmhDataPoint.header.creation_date_time)",

        	"valueQuantity  // the actual results mapped from body.step_count  - note that I added optional UCUM units from the lookup tables": {
        		"value": %(OmhDataPoint.body.stepCount),
        		"unit": "steps",
        		"system": "http://unitsofmeasure.org",
        		"code": "{steps}"
        	}
           "device //  could be mapped from OmhDataPoint.header.acqusitionProvenance elements as well" :
           {"display" : "%(OmhDataPoint.header.acqusitionProvenance.sourceName)"}
        }