Operation Definition

<?xml version="1.0" encoding="UTF-8"?>

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Measure-care-gaps"/> 
  <text> 
    <status value="generated"/> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p class="res-header-id">
        <b> Generated Narrative: OperationDefinition Measure-care-gaps</b> 
      </p> 
      <a name="Measure-care-gaps"> </a> 
      <a name="hcMeasure-care-gaps"> </a> 
      <p> URL: [base]/Measure/$care-gaps</p> 
      <p> URL: [base]/Measure/[id]/$care-gaps</p> 
      <h3> Parameters</h3> 
      <table class="grid">
        <tr> 
          <td> 
            <b> Use</b> 
          </td> 
          <td> 
            <b> Name</b> 
          </td> 
          <td> 
            <b> Scope</b> 
          </td> 
          <td> 
            <b> Cardinality</b> 
          </td> 
          <td> 
            <b> Type</b> 
          </td> 
          <td> 
            <b> Binding</b> 
          </td> 
          <td> 
            <b> Documentation</b> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> periodStart</td> 
          <td/>  
          <td> 1..1</td> 
          <td> 
            <a href="datatypes.html#date">date</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The start of a gaps through period. This may be the start of the measurement period
                 defined by a measure, or a customized desired performance period start date determined
                 by a payer, a provider, a measure program, and etc.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> periodEnd</td> 
          <td/>  
          <td> 1..1</td> 
          <td> 
            <a href="datatypes.html#date">date</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The end of a gaps through period (the gaps through date). The gaps through date
                 could be a past date or a future date. For example, today's date is 2020-06-18,
                 1) if periodEnd date is 2020-09-30, it returns gaps through 2020-09-30, and 2)
                 if the periodEnd date is 2020-05-31, it returns gaps through 2020-05-31.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> subject</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#string">string</a> 
            <br/>  (
            <a href="search.html#reference">reference</a> )
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> Subject for which the care gaps report will be produced</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> subjectGroup</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="group.html">Group</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> Subject for which the gaps in care report will be created is provided as a Group
                 resource.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> parameters</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="parameters.html">Parameters</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> Any input parameters for the Measure evaluation. If the measure uses CQL, the parameter
                 types are mapped to CQL as specified in the Parameters and Data Requirements section
                 of the Using CQL with FHIR Implementation Guide. Any parameters defined in this
                 input will be bound by name to parameters defined in the logic library referenced
                 from library element of the Measure. If a parameter appears more than once in the
                 input Parameters resource, it is represented with a List in the input CQL. If a
                 parameter has parts, it is represented as a Tuple in the input CQL.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> practitioner</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#string">string</a> 
            <br/>  (
            <a href="search.html#reference">reference</a> )
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> Reference to a 
                <a href="practitioner.html">Practitioner</a>  for which the gaps in care report will be created. For a practitioner focused
                 gaps in care report, this is a required In Parameter. The Server needs to make
                 sure that practitioner is authorized to get the gaps in care report for and know
                 what measures the practitioner are eligible or qualified.
              </p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> organization</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#string">string</a> 
            <br/>  (
            <a href="search.html#reference">reference</a> )
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> Reference to an 
                <a href="organization.html">Organization</a>  for which the gaps in care report will be created. Either 'organization' or 'organizationRes
                ource' SHALL be provided, but not both.
              </p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> organizationResource</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="organization.html">Organization</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> Organization for which the gaps in care report will be created is provided as an
                 Organization resource. Either 'organization' or 'organizationResource' SHALL be
                 provided, but not both.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> status</td> 
          <td/>  
          <td> 1..*</td> 
          <td> 
            <a href="datatypes.html#code">code</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> Indicates status of a care gap. For all [open, closed, and prospective gaps], three
                 seperate status parameters must be provided. For a positive proportion measure,
                 gap means the patient is not in the numerator. For an inverse (negative) proportion
                 measure (e.g., Diabetes: Hemoglobin A1c (HbA1c) Poor Control (&gt; 9%)), gap means
                 the patient is in the numerator.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> measureId</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="datatypes.html#id">id</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The id of a Measure resource that is on the server for which the gaps in care report
                 will be created. E.g., the id of the Measure resource for Breast Cancer Screening
                 measure.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> measureIdentifier</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="datatypes.html#string">string</a> 
            <br/>  (
            <a href="search.html#token">token</a> )
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The business identifier of a measure for which the gaps in care will be reported.
                 E.g., CMS125 is a CMS assigned identifier for the Breast Cancer Screening eCQM
                 in their system. Note that the type of this parameter is a string with a search
                 type of 
                <a href="https://www.hl7.org/fhir/search.html#token">token</a> , so the $care-gaps operation has only simple input parameters and may be invoked
                 using GET.
              </p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> measureUrl</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="datatypes.html#canonical">canonical</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The URL of a measure for which the gaps in care report will be created. A measure
                 URL is specified in the 
                <a href="https://www.hl7.org/fhir/measure-definitions.html#Measure.url">url</a>  element of the Measure resource. The measure URL remains the same when the measure
                 is stored on different servers.
              </p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> measureResource</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="measure.html">Measure</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The measure for which the gaps in care report will be created is provided as a
                 Measure resource.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> measure</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="datatypes.html#string">string</a> 
            <br/>  (
            <a href="search.html#reference">reference</a> )
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The measure for which the gaps in care report will be created. This parameter is
                 only required when the operation is invoked on the resource type, it is not used
                 when invoking the operation on a Measure instance</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> manifest</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#canonical">canonical</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> Specifies an asset-collection library that provides dependency version resolution
                 and expansion rules for the operation. See the description of manifest in the Canonical
                 Resource Management Infrastructure IG for a complete description of how manifest
                 values are used to provide defaults for dependency version resolution and expansion
                 parameters. Parameters specified directly in the operation override behaviors specified
                 by the manifest parameter. In general, if this parameter is supplied, it is expected
                 to be used in nested operation calls. For example, in evaluating a measure, if
                 the expansion of a value set is required, this parameter SHALL be supplied to that
                 expansion.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> isDocument</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#boolean">boolean</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The isDocument parameter controls whether a Gaps in Care Composition is returned
                 in the Bundle (i.e. if the Bundle is of type 'Document'). When 'true,' the returned
                 Bundles contain the Gaps in Care Composition. This parameter defaults to 'true.'</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> OUT</td> 
          <td> return</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="bundle.html">Bundle</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The $care-gaps operation returns zero or more document Bundles, one for each input
                 subject. Consistent with FHIR Documents generally, each Bundle SHALL have a Composition
                 as the first entry in the document Bundle, and that Composition SHALL be limited
                 to a single subject. See the 
                <a href="https://build.fhir.org/clinicalreasoning-quality-reporting.html#bundles-organized-by-subject">guidance on Bundle structure</a>  for discussion about the Bundle content and organization.
Note that even though there is a single parameter named return of type Bundle,
                 it is a multi-cardinality parameter, and so will still be returned using a Parameters
                 resource, as described in the general operations framework 
                <a href="https://hl7.org/fhir/R4/operations.html#response">https://hl7.org/fhir/R4/operations.html#response</a> .
              </p> 

            </div> 
          </td> 
        </tr> 
      </table> 
      <div> 
        <p> The effect of invoking this operation is to calculate a set of measures for a particular
           topic (e.g. Preventive Care and Screening) and return a document describing the
           results of each measure for the given subject. Note that it is up to the server
           to determine whether or not the generated care gaps report is persisted. If the
           server does not persist the results, the operation does not affect state and can
           be invoked with a GET</p> 

      </div> 
    </div> 
  </text> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">
    <valueInteger value="3"/> 
  </extension> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status">
    <valueCode value="trial-use"/> 
  </extension> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-wg">
    <valueCode value="cqi"/> 
  </extension> 
  <url value="http://hl7.org/fhir/OperationDefinition/Measure-care-gaps"/> 
  <version value="6.0.0-ballot3"/> 
  <name value="CareGaps"/> 
  <title value="Care Gaps"/> 
  <status value="draft"/> 
  <kind value="operation"/> 
  <experimental value="false"/> 
  <date value="2025-10-28T04:37:24+00:00"/> 
  <publisher value="HL7 International / Clinical Quality Information"/> 
  <contact> 
    <telecom> 
      <system value="url"/> 
      <value value="http://hl7.org/fhir"/> 
    </telecom> 
    <telecom> 
      <system value="email"/> 
      <value value="fhir@lists.hl7.org"/> 
    </telecom> 
  </contact> 
  <contact> 
    <telecom> 
      <system value="url"/> 
      <value value="http://www.hl7.org/Special/committees/cqi"/> 
    </telecom> 
  </contact> 
  <description value="The care-gaps operation is used to determine gaps-in-care based on the results
   of quality measures"/> 
  <jurisdiction> 
    <coding> 
      <system value="http://unstats.un.org/unsd/methods/m49/m49.htm"/> 
      <code value="001"/> 
      <display value="World"/> 
    </coding> 
  </jurisdiction> 
  <affectsState value="false"/> 
  <code value="care-gaps"/> 
  <comment value="The effect of invoking this operation is to calculate a set of measures for a particular
   topic (e.g. Preventive Care and Screening) and return a document describing the
   results of each measure for the given subject. Note that it is up to the server
   to determine whether or not the generated care gaps report is persisted. If the
   server does not persist the results, the operation does not affect state and can
   be invoked with a GET"/> 
  <resource value="Measure"/> 
  <system value="false"/> 
  <type value="true"/> 
  <instance value="true"/> 
  <parameter> 
    <name value="periodStart"/> 
    <use value="in"/> 
    <min value="1"/> 
    <max value="1"/> 
    <documentation value="The start of a gaps through period. This may be the start of the measurement period
     defined by a measure, or a customized desired performance period start date determined
     by a payer, a provider, a measure program, and etc."/> 
    <type value="date"/> 
  </parameter> 
  <parameter> 
    <name value="periodEnd"/> 
    <use value="in"/> 
    <min value="1"/> 
    <max value="1"/> 
    <documentation value="The end of a gaps through period (the gaps through date). The gaps through date
     could be a past date or a future date. For example, today's date is 2020-06-18,
     1) if periodEnd date is 2020-09-30, it returns gaps through 2020-09-30, and 2)
     if the periodEnd date is 2020-05-31, it returns gaps through 2020-05-31."/> 
    <type value="date"/> 
  </parameter> 
  <parameter> 
    <name value="subject"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="Subject for which the care gaps report will be produced"/> 
    <type value="string"/> 
    <searchType value="reference"/> 
  </parameter> 
  <parameter> 
    <name value="subjectGroup"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="Subject for which the gaps in care report will be created is provided as a Group
     resource."/> 
    <type value="Group"/> 
  </parameter> 
  <parameter> 
    <name value="parameters"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="Any input parameters for the Measure evaluation. If the measure uses CQL, the parameter
     types are mapped to CQL as specified in the Parameters and Data Requirements section
     of the Using CQL with FHIR Implementation Guide. Any parameters defined in this
     input will be bound by name to parameters defined in the logic library referenced
     from library element of the Measure. If a parameter appears more than once in the
     input Parameters resource, it is represented with a List in the input CQL. If a
     parameter has parts, it is represented as a Tuple in the input CQL."/> 
    <type value="Parameters"/> 
  </parameter> 
  <parameter> 
    <name value="practitioner"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="Reference to a [Practitioner](practitioner.html) for which the gaps in care report
     will be created. For a practitioner focused gaps in care report, this is a required
     In Parameter. The Server needs to make sure that practitioner is authorized to
     get the gaps in care report for and know what measures the practitioner are eligible
     or qualified."/> 
    <type value="string"/> 
    <searchType value="reference"/> 
  </parameter> 
  <parameter> 
    <name value="organization"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="Reference to an [Organization](organization.html) for which the gaps in care report
     will be created. Either 'organization' or 'organizationResource' SHALL be provided,
     but not both."/> 
    <type value="string"/> 
    <searchType value="reference"/> 
  </parameter> 
  <parameter> 
    <name value="organizationResource"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="Organization for which the gaps in care report will be created is provided as an
     Organization resource. Either 'organization' or 'organizationResource' SHALL be
     provided, but not both."/> 
    <type value="Organization"/> 
  </parameter> 
  <parameter> 
    <name value="status"/> 
    <use value="in"/> 
    <min value="1"/> 
    <max value="*"/> 
    <documentation value="Indicates status of a care gap. For all [open, closed, and prospective gaps], three
     seperate status parameters must be provided. For a positive proportion measure,
     gap means the patient is not in the numerator. For an inverse (negative) proportion
     measure (e.g., Diabetes: Hemoglobin A1c (HbA1c) Poor Control (&gt; 9%)), gap means
     the patient is in the numerator."/> 
    <type value="code"/> 
  </parameter> 
  <parameter> 
    <name value="measureId"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="The id of a Measure resource that is on the server for which the gaps in care report
     will be created. E.g., the id of the Measure resource for Breast Cancer Screening
     measure."/> 
    <type value="id"/> 
  </parameter> 
  <parameter> 
    <name value="measureIdentifier"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="The business identifier of a measure for which the gaps in care will be reported.
     E.g., CMS125 is a CMS assigned identifier for the Breast Cancer Screening eCQM
     in their system. Note that the type of this parameter is a string with a search
     type of [token](https://www.hl7.org/fhir/search.html#token), so the $care-gaps
     operation has only simple input parameters and may be invoked using GET."/> 
    <type value="string"/> 
    <searchType value="token"/> 
  </parameter> 
  <parameter> 
    <name value="measureUrl"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="The URL of a measure for which the gaps in care report will be created. A measure
     URL is specified in the [url](https://www.hl7.org/fhir/measure-definitions.html#Measure.url)
     element of the Measure resource. The measure URL remains the same when the measure
     is stored on different servers."/> 
    <type value="canonical"/> 
  </parameter> 
  <parameter> 
    <name value="measureResource"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="The measure for which the gaps in care report will be created is provided as a
     Measure resource."/> 
    <type value="Measure"/> 
  </parameter> 
  <parameter> 
    <name value="measure"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="The measure for which the gaps in care report will be created. This parameter is
     only required when the operation is invoked on the resource type, it is not used
     when invoking the operation on a Measure instance"/> 
    <type value="string"/> 
    <searchType value="reference"/> 
  </parameter> 
  <parameter> 
    <name value="manifest"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="Specifies an asset-collection library that provides dependency version resolution
     and expansion rules for the operation. See the description of manifest in the Canonical
     Resource Management Infrastructure IG for a complete description of how manifest
     values are used to provide defaults for dependency version resolution and expansion
     parameters. Parameters specified directly in the operation override behaviors specified
     by the manifest parameter. In general, if this parameter is supplied, it is expected
     to be used in nested operation calls. For example, in evaluating a measure, if
     the expansion of a value set is required, this parameter SHALL be supplied to that
     expansion."/> 
    <type value="canonical"/> 
  </parameter> 
  <parameter> 
    <name value="isDocument"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="The isDocument parameter controls whether a Gaps in Care Composition is returned
     in the Bundle (i.e. if the Bundle is of type 'Document'). When 'true,' the returned
     Bundles contain the Gaps in Care Composition. This parameter defaults to 'true.'"/> 
    <type value="boolean"/> 
  </parameter> 
  <parameter> 
    <name value="return"/> 
    <use value="out"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="The $care-gaps operation returns zero or more document Bundles, one for each input
     subject. Consistent with FHIR Documents generally, each Bundle SHALL have a Composition
     as the first entry in the document Bundle, and that Composition SHALL be limited
     to a single subject. See the [guidance on Bundle structure](https://build.fhir.org/clinicalre
    asoning-quality-reporting.html#bundles-organized-by-subject) for discussion about
     the Bundle content and organization. 
 Note that even though there is a single parameter named return of type Bundle,
     it is a multi-cardinality parameter, and so will still be returned using a Parameters
     resource, as described in the general operations framework [https://hl7.org/fhir/R4/operation
    s.html#response](https://hl7.org/fhir/R4/operations.html#response)."/> 
    <type value="Bundle"/> 
  </parameter> 
</OperationDefinition>