Canonical Resource Management Infrastructure Implementation Guide
2.0.0-ballot - STU 2 - Ballot International flag

This page is part of the Canonical Resource Management Infrastructure Implementation Guide (v2.0.0-ballot: STU 2 Ballot) based on FHIR (HL7® FHIR® Standard) R4. This version is a pre-release. The current official version is 1.0.0. For a full list of available versions, see the Directory of published versions

: CRMI Artifact Diff Operation - XML Representation

Page standards status: Trial-use Maturity Level: 4

Raw xml | Download


<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="crmi-artifact-diff"/>
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml"><p class="res-header-id"><b>Generated Narrative: OperationDefinition crmi-artifact-diff</b></p><a name="crmi-artifact-diff"> </a><a name="hccrmi-artifact-diff"> </a><p>URL: [base]/$$artifact-diff</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>source</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#canonical">canonical</a></td><td/><td><div><p>The canonical reference of the source artifact to compare against</p>
</div></td></tr><tr><td>IN</td><td>target</td><td/><td>1..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#canonical">canonical</a></td><td/><td><div><p>A canonical reference of the target artifact which is being compared.</p>
</div></td></tr><tr><td>IN</td><td>compareComputable</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#boolean">boolean</a></td><td/><td><div><p>Whether or not to compare computable content such as ValueSet.compose.include entries.</p>
</div></td></tr><tr><td>IN</td><td>compareExecutable</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#boolean">boolean</a></td><td/><td><div><p>Whether or not to compare executable content such as ValueSet.expansion.contains entries.</p>
</div></td></tr><tr><td>IN</td><td>artifactEndpointConfiguration</td><td/><td>0..*</td><td/><td/><td><div><p>Configuration information to resolve canonical artifacts</p>
<ul>
<li><code>artifactRoute</code>: An optional route used to determine whether this endpoint is expected to be able to resolve artifacts that match the route (i.e. start with the route, up to and including the entire url)</li>
<li><code>endpointUri</code>: The URI of the endpoint, exclusive with the <code>endpoint</code> parameter</li>
<li><code>endpoint</code>: An Endpoint resource describing the endpoint, exclusive with the <code>endpointUri</code> parameter</li>
</ul>
<p><strong>Processing semantics</strong>:</p>
<p>Create a canonical-like reference (e.g.
<code>{canonical.url}|{canonical.version}</code> or similar extensions for non-canonical artifacts).</p>
<ul>
<li>Given a single <code>artifactEndpointConfiguration</code>
<ul>
<li>When <code>artifactRoute</code> is present
<ul>
<li>And <code>artifactRoute</code> <em>starts with</em> canonical or artifact reference</li>
<li>Then attempt to resolve with <code>endpointUri</code> or <code>endpoint</code></li>
</ul>
</li>
<li>When <code>artifactRoute</code> is not present
<ul>
<li>Then attempt to resolve with <code>endpointUri</code> or <code>endpoint</code></li>
</ul>
</li>
</ul>
</li>
<li>Given multiple <code>artifactEndpointConfiguration</code>s
<ul>
<li>Then rank order each configuration (see below)</li>
<li>And attempt to resolve with <code>endpointUri</code> or <code>endpoint</code> in order until resolved</li>
</ul>
</li>
</ul>
<p>Rank each <code>artifactEndpointConfiguration</code> such that:</p>
<ul>
<li>if <code>artifactRoute</code> is present <em>and</em> <code>artifactRoute</code> <em>starts with</em> canonical or artifact reference: rank based on number of matching characters</li>
<li>if <code>artifactRoute</code> is <em>not</em> present: include but rank lower</li>
</ul>
<p>NOTE: For evenly ranked <code>artifactEndpointConfiguration</code>s, order as defined in the
OperationDefinition.</p>
</div></td></tr><tr><td>IN</td><td>artifactEndpointConfiguration.artifactRoute</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#uri">uri</a></td><td/><td/></tr><tr><td>IN</td><td>artifactEndpointConfiguration.endpointUri</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#uri">uri</a></td><td/><td/></tr><tr><td>IN</td><td>artifactEndpointConfiguration.endpoint</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/endpoint.html">Endpoint</a></td><td/><td/></tr><tr><td>IN</td><td>terminologyEndpoint</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/endpoint.html">Endpoint</a></td><td/><td><div><p>An endpoint to use to access terminology (i.e. valuesets, codesystems, naming systems, concept maps, and membership testing) referenced by the resources. If no terminology endpoint is supplied, the server may use whatever mechanism is appropriate for accessing terminology. This could be the server on which the operation is invoked or a third party server accessible to the environment. When a terminology endpoint is provided, the server or third party servers may still be used as fallbacks.</p>
</div></td></tr><tr><td>OUT</td><td>return</td><td/><td>1..1</td><td><a href="http://hl7.org/fhir/R4/parameters.html">Parameters</a></td><td/><td><div><p>The differential in <a href="https://www.hl7.org/fhir/fhirpatch.html">FHIR Patch format</a>.</p>
</div></td></tr></table><div><p>The operation is only valid between two resources of the same type and can optionally include expanding all ValueSets in the dependency tree.</p>
</div></div>
  </text>
  <extension
             url="http://hl7.org/fhir/StructureDefinition/structuredefinition-wg">
    <valueCode value="cds"/>
  </extension>
  <extension
             url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">
    <valueInteger value="4">
      <extension
                 url="http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom">
        <valueCanonical
                        value="http://hl7.org/fhir/uv/crmi/ImplementationGuide/hl7.fhir.uv.crmi"/>
      </extension>
    </valueInteger>
  </extension>
  <extension
             url="http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status">
    <valueCode value="trial-use">
      <extension
                 url="http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom">
        <valueCanonical
                        value="http://hl7.org/fhir/uv/crmi/ImplementationGuide/hl7.fhir.uv.crmi"/>
      </extension>
    </valueCode>
  </extension>
  <url
       value="http://hl7.org/fhir/uv/crmi/OperationDefinition/crmi-artifact-diff"/>
  <version value="2.0.0-ballot"/>
  <name value="CRMIArtifactDiff"/>
  <title value="CRMI Artifact Diff"/>
  <status value="active"/>
  <kind value="operation"/>
  <date value="2025-08-01T18:39:13+00:00"/>
  <publisher value="HL7 International / Clinical Decision Support"/>
  <contact>
    <telecom>
      <system value="url"/>
      <value value="http://www.hl7.org/Special/committees/dss"/>
    </telecom>
  </contact>
  <description
               value="Describes the differences between two knowledge artifacts in [FHIR Patch format](https://www.hl7.org/fhir/fhirpatch.html) by recursively resolving dependencies to get a holistic diff."/>
  <jurisdiction>
    <coding>
      <system value="http://unstats.un.org/unsd/methods/m49/m49.htm"/>
      <code value="001"/>
      <display value="World"/>
    </coding>
  </jurisdiction>
  <code value="artifact-diff"/>
  <comment
           value="The operation is only valid between two resources of the same type and can optionally include expanding all ValueSets in the dependency tree."/>
  <resource value="ActivityDefinition"/>
  <resource value="CapabilityStatement"/>
  <resource value="CodeSystem"/>
  <resource value="CompartmentDefinition"/>
  <resource value="ConceptMap"/>
  <resource value="ExampleScenario"/>
  <resource value="GraphDefinition"/>
  <resource value="ImplementationGuide"/>
  <resource value="Library"/>
  <resource value="Measure"/>
  <resource value="Medication"/>
  <resource value="MedicationKnowledge"/>
  <resource value="MessageDefinition"/>
  <resource value="NamingSystem"/>
  <resource value="OperationDefinition"/>
  <resource value="PlanDefinition"/>
  <resource value="Questionnaire"/>
  <resource value="SearchParameter"/>
  <resource value="StructureDefinition"/>
  <resource value="StructureMap"/>
  <resource value="Substance"/>
  <resource value="TerminologyCapabilities"/>
  <resource value="TestScript"/>
  <resource value="ValueSet"/>
  <system value="true"/>
  <type value="false"/>
  <instance value="false"/>
  <parameter>
    <name value="source"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation
                   value="The canonical reference of the source artifact to compare against"/>
    <type value="canonical"/>
  </parameter>
  <parameter>
    <name value="target"/>
    <use value="in"/>
    <min value="1"/>
    <max value="1"/>
    <documentation
                   value="A canonical reference of the target artifact which is being compared."/>
    <type value="canonical"/>
  </parameter>
  <parameter>
    <name value="compareComputable"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation
                   value="Whether or not to compare computable content such as ValueSet.compose.include entries."/>
    <type value="boolean"/>
  </parameter>
  <parameter>
    <name value="compareExecutable"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation
                   value="Whether or not to compare executable content such as ValueSet.expansion.contains entries."/>
    <type value="boolean"/>
  </parameter>
  <parameter>
    <name value="artifactEndpointConfiguration"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation
                   value="Configuration information to resolve canonical artifacts
* `artifactRoute`: An optional route used to determine whether this endpoint is expected to be able to resolve artifacts that match the route (i.e. start with the route, up to and including the entire url)
* `endpointUri`: The URI of the endpoint, exclusive with the `endpoint` parameter
* `endpoint`: An Endpoint resource describing the endpoint, exclusive with the `endpointUri` parameter

**Processing semantics**:

Create a canonical-like reference (e.g.
`{canonical.url}|{canonical.version}` or similar extensions for non-canonical artifacts).

* Given a single `artifactEndpointConfiguration`
  * When `artifactRoute` is present
    * And `artifactRoute` *starts with* canonical or artifact reference
    * Then attempt to resolve with `endpointUri` or `endpoint`
  * When `artifactRoute` is not present
    * Then attempt to resolve with `endpointUri` or `endpoint`
* Given multiple `artifactEndpointConfiguration`s
  * Then rank order each configuration (see below)
  * And attempt to resolve with `endpointUri` or `endpoint` in order until resolved

Rank each `artifactEndpointConfiguration` such that:
* if `artifactRoute` is present *and* `artifactRoute` *starts with* canonical or artifact reference: rank based on number of matching characters 
* if `artifactRoute` is *not* present: include but rank lower

NOTE: For evenly ranked `artifactEndpointConfiguration`s, order as defined in the
OperationDefinition."/>
    <part>
      <name value="artifactRoute"/>
      <use value="in"/>
      <min value="0"/>
      <max value="1"/>
      <type value="uri"/>
    </part>
    <part>
      <name value="endpointUri"/>
      <use value="in"/>
      <min value="0"/>
      <max value="1"/>
      <type value="uri"/>
    </part>
    <part>
      <name value="endpoint"/>
      <use value="in"/>
      <min value="0"/>
      <max value="1"/>
      <type value="Endpoint"/>
    </part>
  </parameter>
  <parameter>
    <name value="terminologyEndpoint"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation
                   value="An endpoint to use to access terminology (i.e. valuesets, codesystems, naming systems, concept maps, and membership testing) referenced by the resources. If no terminology endpoint is supplied, the server may use whatever mechanism is appropriate for accessing terminology. This could be the server on which the operation is invoked or a third party server accessible to the environment. When a terminology endpoint is provided, the server or third party servers may still be used as fallbacks."/>
    <type value="Endpoint"/>
  </parameter>
  <parameter>
    <name value="return"/>
    <use value="out"/>
    <min value="1"/>
    <max value="1"/>
    <documentation
                   value="The differential in [FHIR Patch format](https://www.hl7.org/fhir/fhirpatch.html)."/>
    <type value="Parameters"/>
  </parameter>
</OperationDefinition>