HL7 FHIR Implementation Guide: minimal Common Oncology Data Elements (mCODE) Release 1 - US Realm | STU Ballot 1

HL7 FHIR Implementation Guide: minimal Common Oncology Data Elements (mCODE) Release 1 - US Realm | STU Ballot 1 - Local Development build (v0.9.1). See the Directory of published versions

Implementation Notes

This page contains miscellaneous information on modeling and FHIR implementation. The content is primarily directed at informaticists and implementers of mCODE. The following topics are addressed:

Conformance Requirements

Relationship to US Core

With one exception (see below), the profiles presented in this guide conform to US Core Implementation Guide (v3.0.0). Each mCODE Profile uses a corresponding US Core profiles as its base profile, and thus, cannot break the rules established by that profile in US Core. For example, if US Core has a required element, by virtue of profile inheritance, mCODE cannot make that element optional. However, it is not true that any instance that conforms to an mCODE profile will automatically conform to US Core. In particular, the use of extensible value sets requires caution. Extensibility is only allowed when an appropriate concept is not available in the US Core value set. Please note:

  • In ComorbidCondition, if an ICD-10-CM code is used, and a semantically equivalent SNOMED-CT code is available, the resulting instance will not conform to US Core.
  • In mCODE Procedures, if an ICD-10-PCS code is used, and a semantically equivalent SNOMED CT or CPT code is available, the resulting instance will not confirm to US Core.
  • In GenomicsReport, a LOINC code must be used, if available. If there is no suitable code in LOINC, then a code from an alternative code system (such as a code from the Genetic Testing Registry can be used.
  • In PrimaryCancerCondition and SecondaryCancerCondition, if an ICD-10-CM code is used, and a semantically equivalent SNOMED-CT code is available, the resulting instance will not conform to US Core.

The one known exception to US Core compliance is in GenomicsReport, where the category attribute is set to 'GE' (Genetics), a code from the Diagnostic Service Section Codes value set. However, US Core requires the category 'LAB' in every diagnostic report containing laboratory results, and restricts the category to 1..1, thus preventing any other categorization. This is assumed to be an oversight in the US Core specifications.

International Version of mCODE

Although the current version of mCODE is US-specific, there is a potential for an international version of mCODE. If interested, please contact one of the authors.

mCODE Roles

At present, two roles are defined:

  • mCODE Data Sender - a participant in exchange of mCODE data who provides mCODE data in response to a data query or autonomously pushes mCODE data to an mCODE receiver. The data sender does not have to be the originator of the data it possesses.
  • mCODE Data Receiver - a participant in exchange of mCODE data who accepts mCODE data from an mCODE Data Sender.

In the future, additional roles may be defined.

"Must Support" Interpretation

In FHIR, the MustSupport flag indicates that implementation shall provide "meaningful support" for the element, as defined by its implementation guide. In mCODE, there are two sources of MustSupport elements: those inherited from US Core, and those defined in mCODE. To conform to US Core, the MustSupport elements inherited from US Core must follow the interpretation of MustSupport defined in US Core.

Elements defined as MustSupport in mCODE do not follow the US Core rules. MustSupport elements defined in mCODE shall be interpreted as follows:

  • mCODE Data Sender - MustSupport is interpreted as "required to be sent if known" (subject to applicable privacy and security rules). That is, every MustSupport element in a profiled mCODE resource SHALL to be provided to an mCODE Data Receiver, if Data Sender has that data.
  • An mCODE Data Receiver SHALL be capable of receiving and storing each required and MustSupport element in mCODE, if the profile has been declared as a "supportedProfile" in the receiver's capability statement.

Unfortunately, FHIR does not have the ability to track the source of MustSupport flags, and the only way to know where a MustSupport flag is defined is by direct comparison of US Core and mCODE profiles.

Required Elements

An mCODE data element is required if any of the following criteria are met:

  • The element is a top-level element (a first-level property of the resource) and its minimum cardinality is > 0 in the profile.
  • The element not a top-level element (a second-level property or below), its minimum cardinality is > 0, and all elements directly containing that element have minimum cardinality > 0 in the profile.
  • The element is not a top-level element, its minimum cardinality is > 0, and its immediate higher-level containing element exists in an instance of the profile.

In other words, a data element may be 1..1, but if it is contained by an optional element, then it is not required unless its containing element is actually present in a given instance of the profile.

mCODE's rules regarding required data elements are the same as US Core's rules. To paraphrase those rules, a Data Sender must provide each required element or an explicit data absent reason for each missing data item.

Minimum Requirement for "mCODE Conformance"

The mCODE IG outlines conformance requirements and expectations for individual mCODE instances in terms of structural constraints and terminology bindings. Any FHIR resources claiming to conform to mCODE must validate against the declared mCODE profile.

At present, there are no additional conformance rules on what mCODE data is to be collected, by whom, and when, or when that data is to be exchanged. mCODE Data Senders and Data Receivers may choose the subset of mCODE resources they support, according to their business needs. For example, a Genomics Laboratory may support GenomicsReport, but not vital signs or staging.

FHIR capability statements describe the capabilities of actual implementation or requirements of a desired solution. This IG does not include sample capability statements. The expectation is to use implementation experience collected during the STU period to model the different types of actors (such as medical oncologist, radiologist, genomics laboratory, etc.), and define appropriate capability statements for each, including search parameters and operations.

Terminology Preferences

This implementation guide supplies terminology bindings drawn primarily from LOINC for "observables", and SNOMED-CT for values, results and findings. When appropriate codes are not available in the preferred vocabulary, alternative vocabularies are used, in the following order of preference: SNOMED-CT (if the element is an observable), NCI Thesaurus and Metathesaurus, and local codes.

The specification of SNOMED US Edition is handled within the FHIR CodeableConcept.version attribute:

{version: "http://snomed.info/sct/731000124108"}

where 731000124108 is the SNOMED namespace assigned to the National Library of Medicine (NLM), who manages the SNOMED US Edition.

Value sets from the FHIR specification and US Core were reused to the extent possible. New value sets where created only when no known existing value sets were deemed to be fit for purpose, or when existing value sets were needed to be extended.


FHIR (and mCODE) allows multiple addresses for a patient. The zip code reported in mCODE should be the one specified by Address.use of "home" and Address.type of "physical".

Body Locations

A single code is often insufficient to precisely determine a body site for the purpose of describing where a tumor is located, where a surgery is targeted, or where a radiation treatment is focused. For example, in breast cancer, the location of a tumor can be described in terms of the radial position (clock face direction) and distance relative to the left or right nipple.

In FHIR, Condition, Procedure, and other resources represent body sites using a single code. In addition, FHIR provides a standard extension, BodyStructure Reference that can be used when a single code is insufficient. However, this approach has not been adopted, for the following reasons:

  • The bodySite attribute is a terminology concept, but BodyStructure is a resource, representing a body site on a specific patient. Concepts and instances are not analogous and cannot be arbitrarily swapped. For example, "3 cm from left nipple at 2 o'clock position" is a conceptual location, but "3 cm from Jane Doe's left nipple at 2 o'clock position" is not.
  • Even if the difference between a terminology concept and an patient-specific resource is overlooked, the BodyStructure resource is insufficient for mCODE's purposes.

Instead, mCODE uses an approach that defines body sites conceptually, and has the required specificity, by introducing three optional extensions on bodySite:

  • AnatomicalOrientation - captures the orientation of the body location, if needed to distinguish from a similar location in another orientation.
  • Laterality - the side of the body the body location, if needed to distinguish from a similar location on the other side of the body
  • RelationToLandmark - Zero or more relationships between a landmark and the body location that helps determine the body location itself. RelationToLandmark itself is a structure that:
    • Specifies the location and type of landmark using a body site code and optional laterality/orientation,
    • Specifies the direction from the landmark to the body location, and
    • Specifies the distance from the landmark to the body location.

Vital Sign Profiles

The vital sign profiles defined by mCODE are consistent with the FHIR vital sign profiles, which are incorporated by reference into US Core v3. The difference between FHIR and mCODE vital signs is that mCODE provides for reporting of preconditions, body positions, blood pressure method, and blood pressure body location, with appropriate value sets. The vital signs model in mCODE is aligned with the Vital Signs Implementation Guide being developed in cooperation with the Clinical Information Modeling Initiative (CIMI) Work Group.

Although mCODE defines its own vital signs profiles, if and when detailed vital signs profiles are standardized in a widely-accepted FHIR IG, mCODE will likely switch over to those profiles.

Laboratory Profiles

Many laboratory profiles in mCODE are not shown on the main Profiles page, but are listed with the panels they are a part of. To assure naming uniqueness over thousands of LOINC laboratory tests, laboratory profile names have been formulated as a concatenation of the LOINC Component, Property, Time, System, Scale, and Method. Where the concatenation exceeds the FHIR element name length limitation of 64 characters, some additional contractions have been introduced. Although mCODE defines its own laboratory profiles, if and when detailed laboratory profiles are standardized in a widely-accepted IG, mCODE will likely switch over to those profiles.

mCODE includes the following 72 laboratory profiles:

Approved for Public Release. Distribution Unlimited. Case Number 16-1988