minimal Common Oncology Data Elements (mCODE) Implementation Guide
2.1.0 - STU 2.1 United States of America flag

This page is part of the HL7 FHIR Implementation Guide: minimal Common Oncology Data Elements (mCODE) Release 1 - US Realm | STU1 (v2.1.0: STU 2) based on FHIR R4. This is the current published version. For a full list of available versions, see the Directory of published versions

Change Log

mCODE STU 2.1 Update (December 2022)

The primary goal of the STU 2.1 update is to incorporate newly-issued SNOMED CT codes. The following changes have been made in this update:

  • PrimaryCancerCondition’s stage.type value set binding was corrected. It should have indicated the staging method that gave rise to the value appearing in stage.summary (such as AJCC Version 8).
  • Corrected extended example, which formerly used invalid stage “pM0”. Replaced with a data absent reason “not applicable”.
  • “SNOMED-CT” was changed to the preferred form “SNOMED CT” in narratives
  • New SNOMED Codes issued since the STU2 publication have replaced temporary codes:
    • #1204242009 “External beam radiation therapy using particle scanning technique (procedure)”
    • #1217123003 “Radiotherapy Course of Treatment (regime/therapy)”
    • #1201745009 “Internal Target Volume (observable entity)”
    • #1201746005 “Internal Gross Tumor Volume (observable entity)”
    • #1162586008 “Irradiated volume of organ at risk (observable entity)”
    • #551001000124108 “Cancer in partial remission (finding)”
    • #550991000124107 “Cancer in full remission(finding)”
    • #1162782007 “Three dimensional external beam radiation therapy (procedure)”
    • #1162492000 “Tumor bed (morphologic abnormality)”
    • #1217011006 “non-adjacent (qualifier)”
    • #1162616006 “Lymph node level IA (qualifier value)”
    • #1162617002 “Lymph node level IB (qualifier value)”
    • #1162620005 “Lymph node level IVA (qualifier value)”
    • #1162621009 “Lymph node level IVB (qualifier value)”
    • #1162622002 “Lymph node level VA (qualifier value)”
    • #1162623007 “Lymph node level VB (qualifier value)”
    • #1162624001 “Lymph node level VC (qualifier value)”
    • #1162625000 “Lymph node level VIA (qualifier value)”
    • #1162626004 “Lymph node level VIB (qualifier value)”
    • #1162628003 “Lymph node level VIIA (qualifier value)”
    • #1162627008 “Lymph node level VIIB (qualifier value)”
    • #1162618007 “Lymph node level VIII (qualifier value)”
    • #1162619004 “Lymph node level IX (qualifier value)”
    • #1162614009 “Lymph node level X (qualifier value)”
    • #1162615005 “Lymph node level XA (qualifier value)”
    • #1162613003 “Lymph node level XB (qualifier value)”
  • Corrected temporary codes to align with SNOMED USCRS Jira Tickets. These changed due to resubmission of the SNOMED USCRS requests as observable entity type.
    • bowel space (body structure) (USCRS-33351 ==> bowel space (observable entity) (USCRS-34356)
    • small bowel space (body structure) (USCRS-33352) ==> small bowel space (observable entity) USCRS-34358)

mCODE STU 2 Publication Version (January 2021)

General Changes

  • Updated the Data Dictionary content.
  • A glossary of radiotherapy terms was added.
  • Updated the mCODE diagram to reflect STU 2 changes. Embedded links to FHIR artifacts were added.
  • Re-arranged the top-level menus for easier navigation.
  • Provided separate pages containing the different types of FHIR artifacts (e.g., Profiles, ValueSets)
  • Updated lists of artifacts on “Content by Group” pages.
  • Added external value sets used by mCODE to FHIR Artifacts Value Sets page
  • Updated terminology page to include code system identifiers recommended by HL7 Terminology Authority, and to document local code systems.
  • Local code systems have been consolidated and reorganized to reduce their number. Local codes have been standardized to reflect codes requested from SNOMED and LOINC.
  • Added FSH rendering in notes section for all example instances (e.g., this example)
  • Added more readable renderings of all capability statements.
  • Made values required in all extensions because extensions should never appear if there is no value. FHIR-33003
  • All definitions have been reviewed and edited and numerous improvements and corrections made to narrative content.


  • Replaced the term “Obligation to Implement (OTI)” with more straightforward “Must Implement” in explanation of profile conformance
  • Simplified and clarified explanations of what profiles and data elements must be implemented by mCODE users.
  • Narrative now refers consistently “in-scope patient”, instead of “mCODE patient” due to confusion about the meaning of the latter term.

Patient Group Changes

  • All references to subject or patient now reference CancerPatient. Any patient that conforms to USCore is conformant. FHIR-32166
  • Removed the local code system ResourceIdentifierCS that contained only one code (#mcode-patient), and replaced #mcode-patient with the NCI code for cancer patient, NCI#C19700. This affects the profile MCODEPatientGroup and the way of querying for the list of “in-scope” patients.
  • Changed slicing on MCODEPatientBundle to required each resource in the bundle to populate meta.profile.

Assessment Group Changes

  • Replaced local codes for Comorbidities with codes in the LoincRequestedCS code system, since codes have now been requested in LOINC.
  • Clarified that the overall risk score should be included in the Elixhauser Comorbidity, and explained cases where might be missing. FHIR-32280, FHIR-32280
  • Removed “unknown” from value set in Elixhauser Comorbidity profile components since unknown is not a part of the Elixhauser score. FHIR-32280

Disease Group Changes

  • Laterality broken out into separate extension in PrimaryCancerCondition, SecondaryCancerCondition, TumorSpecimen, GenomicSpecimen because laterality is reported as a separate required value in most registry reports. FHIR-32340
  • Changed the definition of CancerStagingSystemVS to an intensional set containing descendants of SCT#254292007 “Tumor staging (tumor staging)”. The includes codes for AJCC staging (version 6, 7, and 8) and many other specialized staging systems.Changed the definition of CancerStagingSystemVS to an intensional set containing descendants of SCT#254292007 “Tumor staging (tumor staging)”. The includes codes for AJCC staging (version 6, 7, and 8) and many other specialized staging systems. FHIR-32663
  • Changed name of extension from LocationQualifier to BodyLocationQualifier to make the semantics more clear. FHIR-32345, FHIR-32348

Treatment Group Changes

  • Incorporated the modality and technique extensions into a combined RadiotherapyModalityAndTechnique extension that includes invariants that restrict the allowed combinations using invariants
  • Aligned the RadiotherapyTreatmentLocationVS and RadiotherapyTreatmentLocationQualifierVS value sets to American Association of Physicists in Medicine (AAPM) TG-263 anatomy terms and provide a mapping to SNOMED-CT concepts and qualifiers. FHIR-33343
  • Added the identifier slice to RadioTherapyVolume and RadiotherapyCourseSummary.
  • Laterality broken out into separate extension in CancerRelatedSurgicalProcedure. FHIR-32340
  • TumorMarkerTestVS value set has been curated to better capture the intended scope of tumor marker tests.
  • BrachytherapyTreatmentPhase and RadiotherapyTreatmentPhase profiles and examples dropped because it was determined that this was too much detail for mCODE. Phase profiles will reappear in the planned CodeX Radiation Therapy FHIR Implementation Guide. FHIR-33340
  • Changed valued in TreatmentTerminationReasonVS to SNOMED-CT situations and findings. Added new values including SCT#399307001 "Lost to follow-up (finding)" and SCT#419620001 "Death (event)". FHIR-32832
  • Radiotherapy Modality Value Set and Radiotherapy Technique Value Set are now defined by inclusion of the modality and technique value sets for Brachytherapy and Teleradiotherapy rather than by enumeration. FHIR-32263
  • Descriptions for the Elixhauser ThyroidOther and NeuroOther VS have been clarified. FHIR-32350
  • Dropped the context restrictions on TreatmentIntent, Modality, and Technique extensions to permit them to be used in other resources in the future. FHIR-32243
  • Added tables with definitions and compatibility for all radiotherapy and brachytherapy modalities and techniques. FHIR-32244, FHIR-32246, FHIR-32247
  • Updated language defining brachythereapy and teleradiotherapy treatment phase so as not to imply that phases are sequential. FHIR-32256
  • Replaced radiotherapy modality and technique UMLS and local codes with approved SNOMED-CT codes. Local codes have been removed from the radiotherapy code system, and the radiotherapy code system has been removed. FHIR-32261
  • Changed name of value set from TreatmentIntentVS to ProcedureIntentVS because “procedure” was considered broader than “treatment”. FHIR-32264
  • Clarified that total dose in a Phase is not cumulative across multiple phases. FHIR-32266
  • Clarify that the number of fractions is per volume in Course Summary, but not per volume in a Phase. FHIR-32267.
  • The invariant requiring a reason for medication and surgery (mcode-reason-required) now generates warning instead of an error. FHIR-32387

Genomics Group Changes

  • Renamed CancerGeneticVariant to GenomicVariant to reflect wider scope of this profile. FHIR-32888
  • Renamed CancerGenomicsReport to GenomicsReport because it is not specific to cancer, and make that profile more broadly applicable.
  • GenomicVariant now includes additional components for molecular consequence, clinical significance, variant category, and copy number.
  • Added Values Urine, Stool to GenomicSpecimenTypeVS value set. The suggested term Source, other was not added because the value set binding is extensible. FHIR-32827
  • Primary and Secondary cancer value sets have been aligned with CDC state cancer reporting practices. FHIR-32956

Outcome Group Changes

mCODE STU 2 Ballot Version (May 2021)

The following summarizes changes to the STU1 release for the STU2 Ballot (May 2021). Many of these changes have been taken in response to input from the HL7 community. Issue numbers refer to the HL7 Jira (free account registration required).

A comprehensive listing of differences in FHIR artifacts between STU 1 and STU 2 is given in the Data Dictionary Differential (DDD) spreadsheet. This file is meant to supplement rather than replace the content in this Implementation Guide, and the Implementation Guide takes precedence in any cases where the DDD appears to conflict with it.

General Changes

Patient Group Changes

  • Certain profiles have been moved to the Assessments group
  • A new profile, MCODEPatientGroup, has been added to represent the patients to be considered in scope for mCODE.
  • A new profile, MCODEPatientBundle, has been added for the purpose of returning all mCODE resources related to a CancerPatient.


  • Changed the name of this group from Labs & Vital to Assessment and moved Performance Assessments and Comorbidities into this group.
  • Comorbidities have been redesigned to capture the presence or absence of all comorbidities in one Observation.




  • GenomicVariant contains an additional component for DNA change type.


mCODE 1.0.0 STU 1

The following are changes made to the mCODE 0.9.1 September 2019 Ballot Release that are in the mCODE 1.0.0 STU1 release.


  • The following profiles have been added: GenomicSpecimen, RegionStudied to support greater alignment between mCODE and the Clinical Genomics Reporting FHIR IG STU1..
  • The GeneticVariant profile has additional components which conform to equivalent components in the CG Reporting IG Variant profile: geneStudied, variationCode, genomicDNAChange, genomicSourceClass, aminoAcidChange, aminoAcidChangeType, cytogeneticLocation, and cytogeneticNomenclature.
  • The MedicationStatement profile name has changed to CancerRelatedMedicationStatement. This profile now constrains the reason reference to only primary and secondary cancer conditions.

Corrections and Modifications to Existing Content

  • The following mCODE profiles no longer appear and instead document preferred use of FHIR base profiles: BloodPressure, BodyWeight, BodyHeight, CBCWAutoDifferentialPanel, ComprehensiveMetabolic2000SerumOrPlasmaPanel.
  • Genomics-related profiles GeneticVariantTested and GeneticVariantFound are combined into one profile, GeneticVariant.
  • GenomicsReport onco-core-RegionStudied-extension is migrated to a slice under DiagnosticReport.result with a reference to a new profile, RegionStudied.
  • GenomicsReport obf-SpecimenType-extension is migrated to a slice under DiagnosticReport.result with a reference to a new profile, GenomicSpecimen.
  • DiagnosticReport.category cardinality changed from 1..1 to 1..*
  • Replaced references of CIMPL to references of FHIR Shorthand and SUSHI.
  • ECOGPerformanceStatus Observation.code and Observation.interpretation changed to align with the LOINC equivalent of ECOG score (89247-1) and interpretation (LOINC Answer List LL529-9).
  • KarnofskyPerformanceStatus Observation.code and Observation.interpretation changed to align with the LOINC equivalent of Karnofsky score (89243-0) and interpretation (LOINC Answer List LL4986-7).

mCODE 0.9.1 September 2019 Ballot Release

The following are changes relative to mCODE 0.9.0 that appear in the mCODE 0.9.1 September 2019 Ballot Release


  • Updated to FHIR Release 4 from DSTU 2.
  • Changed base class of mCODE laboratory panels (CBC and CMP) from Observation to DiagnosticReport.
  • Documented mCODE compliance criteria.
  • Documented preferred value sets for extensible binding and affect on US Core compliance.
  • Changed HistologyMorphologyBehaviorVS value set to descendants of SCT#367651003 (Malignant neoplasm of primary, secondary, or uncertain origin (morphologic abnormality)), from descendants of SCT#108369006 (Neoplasm (morphologic abnormality)), because the latter brought in some concepts that do not represent malignant neoplasms.

Corrections and Modifications to Existing Content

  • Updated code systems to new FHIR R4 base URL, (previously was
  • Changed profile name from GeneticMutationTested to GeneticVariant.
  • Corrected mapping so the reference to PrimaryCancerCondition in all staging-related observations uses the existing ‘focus’ attribute.
  • Eliminated AnatomicalOrientation.
  • Eliminated ClockDirection as a separate value set because values are incorporated in logically-defined SNOMED CT AnatomicalOrientationVS.
  • Re-wrote the introductory narratives to consolidate multiple pages.
  • Changed clinicalStatus on PrimaryCancerCondition and SecondaryCancerCondition from 1..1 to 0..1.
  • Typographical fixes to multiple documentation pages.
  • Eliminated reference range from GeneticVariant and components of GeneticVariantFound.
  • Improved the definition of “curative” and “palliative” in TreatmentIntentVS.
  • Corrected the definition of TreatmentIntent.
  • Improved the explanation of the relationships between the genomics-related profiles.
  • Updated examples to validate against FHIR R4 and other changes to the profiles.
  • Changed blood pressure test code to LNC#85354-9 “Blood pressure panel with all children optional” to align with FHIR
  • Restored device attribute on TumorMarkerTest since laboratories do report it on occasion.
  • Added string as an allowable datatype for TumorMarkerTest.value[x], since it is a valid datatype for some of the tests included in TumorMarkerTestVS.
  • Changed cardinality of ECOGPerformanceStatus.value and KarnofskyPerformanceStatus.value to 1..1 and ECOGPerformanceStatus.dataAbsentReason and ECOGPerformanceStatus.dataAbsentReason to 0..0
  • Changed cardinality of GeneticVariant.referenceRange to 0..0.
  • Changed cardinality of referenceRange for GeneticVariantFound.component[VariantFoundIdentifier], GeneticVariantFound.component[VariantFoundHGVSName] and GeneticVariantFound.component[VariantFoundDescription] and to 0..0.
  • Clarified description of HistologyMorphologyBehaviorVS regarding the use of ICD-O-3 behavior codes.
  • Corrected descriptions for multiple codes in the ComorbidConditionVS.
  • Updated Data Dictionary to reflect FHIR R4 and other changes to the Implementation Guide.
  • Renamed PrimaryCancerConditionVS to PrimaryOrUncertainBehaviorCancerDisorderVS, for greater alignment with value set content.
  • Renamed extension prefixes from shr-core to obf-datatype.
  • Replaced onco-core-geneStudied-extension with observation-geneticsGene standard extension in GeneticVariant.
  • Corrected the definition of obf-RadiationDosePerFraction-extension.
  • Renamed vital-precondition-extension to vital-preconditionCode-extension to distinguish from precondition whose datatype is Reference().
  • Improved the definition for obf-RadiationFractionsDelivered-extension.
  • Replaced locally defined LateralityVS with FHIR-defined laterality value set in obf-datatype-Laterality-extension.
  • Improved definition of onco-core-EvidenceType-extension.
  • Replaced obf-dateOfDiagnosis-extension with condition-assertedDate standard extension in PrimaryCancerCondition and SecondaryCancerCondition.
  • Added logical definition to TNM-related value sets to include all codes from AJCC staging systems.
  • Removed references to MedicationRequest on basedOn attribute for TNMPrimaryTumorCategory, TNMRegionalNodesCategory, TNMDistantMetastasesCategory, KarnofskyPerformanceStatus and ECOGPerformanceStatus.