minimal Common Oncology Data Elements (mCODE) Implementation Guide
4.0.0 - STU4 United States of America flag

minimal Common Oncology Data Elements (mCODE) Implementation Guide, published by HL7 International / Clinical Interoperability Council. This guide is not an authorized publication; it is the continuous build for version 4.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-mCODE-ig/ and changes regularly. See the Directory of published versions

Conformance Expectations

This section outlines requirements and recommendations for mCODE participants. The conformance verbs - SHALL, SHOULD, and MAY - are defined in FHIR Conformance Rules. MUST, MUST NOT, SHALL NOT, and REQUIRED are to be interpreted as described in RFC 2119.

mCODE Participant Roles

Two roles for mCODE Participants 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. The Data Sender role is similar to a US Core Responder, except the data sent is not assumed to be a response to a query.
  • mCODE Data Receiver - a participant in exchange of mCODE data who accepts mCODE data from an mCODE Data Sender. The Data Receiver may receive data as part of a predetermined workflow, or initiate the exchange via a query or on a regular basis via subscription. The Receiver role is similar to a US Core Requestor, except the data does not have to be explicitly requested.

This IG currently only provides CapabilityStatements and documentation for "pull" (query-response) architectures, however, regardless how exchanges occur, all participants SHALL follow the conformance requirements in this IG, except those specifically identified as applying only to pull architectures.

"SHALL" Requirements for Conformance

mCODE participants SHALL meet the following requirements for conformance:

  1. Identify in-scope patients
  2. Follow conformance requirements for supported profiles
  3. Populate and meaningfully process mCODE resources
  4. Support querying mCODE-conforming resources
  5. Publish a CapabilityStatement identifying supported profiles and operations
  6. Support US Core conformance requirements

Identify In-Scope Patients

To facilitate conformance testing, testing software must be able to determine which patients are "in-scope" (meaning cancer patients whose data is presented or exchanged with the intention of conforming to mCODE). In general, all patients with confirmed cancer diagnoses SHOULD be covered by mCODE, but mCODE provides several ways to identify this group of in-scope patients. See the Identifying In-Scope Patients page for details.

Follow Conformance Requirements for Supported Profiles

The information produced and consumed by mCODE participants is defined by a set of profiles. Both Senders and Receivers must conform to the expectations set by these profiles. See the Profile Conformance page for details.

Populate and Meaningfully Process mCODE Resources

mCODE Senders MUST be able to populate data elements Must-Support (MS) obligations, for all profiles they support (as declared in their CapabilityStatement). Receivers MUST be able to meaningfully process elements with MS obligations for each of the profiles they support (as declared in their CapabilityStatement). "Able to Populate" and "Meaningfully Process" have particular meanings, as discussed on the Profile Conformance page.

Support Querying mCODE-Conforming Resources

mCODE defines operations that Senders and Receivers use to exchange mCODE information. In a "pull" (query-response) architecture, Senders SHALL support the requests below for retrieving all resources conforming to a given mCODE Profile, UNLESS they do not support the profile at all (see "Support All mCODE Profiles" below). For more details on the conformance requirements for Senders and Receivers, see Profile Conformance.

Note that the requests below may return resources associated with patients who are not in-scope patients. These resources MAY not conform to mCODE profiles.

Publish a CapabilityStatement Identifying Supported Profiles and Operations

Each mCODE participant SHALL publish a FHIR CapabilityStatement listing their supported profiles, by declaring the profile in CapabilityStatement.rest.resource.supportedProfile. The CapabilityStatement SHALL be returned in response to a GET [base]/metadata request.

ALL mCODE participants SHALL at minimum support the CancerPatient and PrimaryCancerCondition profiles.

Support US Core Conformance Requirements

Additional conformance requirements from US Core apply to RESTful interactions, searches, and resource formats in mCODE. mCODE "inherits" all US Core conformance requirements. US Core provides base profiles for many (but not all) mCODE profiles, outlines expectations for handling of missing or unknown data elements, and outlines how to associate provenance information associated with collection, transfer, and updating clinical information.

International users of mCODE may find US Core an impediment to implementation. Application of mCODE to other countries is open to further discussion.

"SHOULD" Recommendations for Conformance

mCODE participants SHOULD meet the following requirements for conformance:

  1. Support all mCODE Profiles
  2. Support the mCODE Patient Bundle

Support All mCODE Profiles

In addition to supporting the core profiles as described above, mCODE participants SHOULD support all profiles defined in mCODE UNLESS the participant does not anticipate supplying or consuming a certain type of data, usually by virtue of playing a limited or specialized role in clinical or information workflows. For example, a genomics laboratory may support GenomicsReport, but not vital signs or staging.

Participants SHOULD also support the non-mCODE-specific profiles that are considered part of an mCODE Patient Bundle, such as blood pressure.

Support the mCODE Patient Bundle

The mCODE Patient Bundle provides a mechanism to retrieve cancer-related resources for an in-scope Patient. Participants SHOULD support this CapabilityStatement (sender/receiver) for the mcode-patient-everything operation, which retrieves an mCODE Patient Bundle for a given Patient ID.

GET [base]/Patient/[id]/$mcode-everything

This endpoint SHALL support start and end parameters and MAY support the _since, _type, and _count parameters, which operate the same as in the Patient/[id]/$everything operation. The _since parameter is provided to support periodic queries to obtain additional information that has changed about the patient since the last query.

For some types of resources, such as vital signs, a large number of resources may exist. Senders may use their discretion to select the resources that are most relevant, e.g., a subset of the vital signs that were recorded. Alternatively, servers may refuse to serve the request and indicate that the client asked for too much data (see OperationOutcome). To limit the number of included resources, callers MAY specify a _count parameter that pages through the results.

Retrieving an mCODE Patient BundlemCODE Data ReceivermCODE Data SenderGET [base]/Patient/[id]/$mcode-everythingHTTP response containing mCODE Patient Bundle

mCODE Patient Bundles SHALL be identified by an id value that matches the id in the contained CancerPatient-conforming resource.

Use meta.profile to Signal Conformance

Participants SHOULD populate meta.profile elements for all resources to indicate which profiles the resources claim to conform to. Servers SHOULD also implement profile search, which allows participants to query using the _profile parameter to return resources conforming to the profiles declared in meta.profile.

Profile search and population of meta.profile originate as "SHALL" requirements in the base FHIR specification; they are not additional requirements imposed by mCODE. However, in practice, few implementations have followed these requirements. Refer to the FHIR Documentation on supported profiles for details.

Capability Statements

Operations