# Expression Repository with HL7 FHIR

{% hint style="danger" %}
**Under development**

This section is still under active development, and the API examples will change as reference implementations mature and this is discussed with the community of practic
{% endhint %}

## Solution Overview <a href="#id-5.4.2expressionrepositorywithhl7fhir-solutionoverview" id="id-5.4.2expressionrepositorywithhl7fhir-solutionoverview"></a>

To represent an expression repository using FHIR terminology services, the required solution will depend on what approach is taken to uniquely refer to the expressions:

* The expressions themselves may be used as an identifier
  * With this approach, a **CodeSystem Supplement** will be created and function as the expression repository
    * This supplements the applied SNOMED CT CodeSystem
* A separate identifier is created for each expression
  * With this approach, the following FHIR [terminology resources](https://hl7.org/fhir/terminology-module.html) are required
    * a [**CodeSystem Supplement**](http://hl7.org/fhir/codesystem.html) to function as the expression repository
      * This supplements the applied SNOMED CT CodeSystem
    * a [**CodeSystem**](http://hl7.org/fhir/codesystem.html) to hold the expression identifiers
    * a [**ConceptMap**](http://hl7.org/fhir/conceptmap.html) to hold the association between the expression identifiers and the expressions

<figure><img src="https://confluence.ihtsdotools.org/download/attachments/180917852/FHIR%20TS%20with%20exprep.png?version=1&#x26;modificationDate=1680007996000&#x26;api=v2" alt=""><figcaption><p>Design of an expression repository within an HL7 FHIR enabled terminology server</p></figcaption></figure>

## Services <a href="#id-5.4.2expressionrepositorywithhl7fhir-services" id="id-5.4.2expressionrepositorywithhl7fhir-services"></a>

With this implementation, the defined operations for CodeSystems and ConceptMaps can be utilized to support the services required for an expression repository. Please refer to the HL7 FHIR documentation for further details:

* **CodeSystem**
  * [$lookup](http://hl7.org/fhir/codesystem-operation-lookup.html)
  * [$validate-code](http://hl7.org/fhir/codesystem-operation-validate-code.html)
  * [$subsumes](http://hl7.org/fhir/codesystem-operation-subsumes.html)
* **ConceptMap**
  * [$translate](http://hl7.org/fhir/conceptmap-operation-translate.html)
  * [$closure](http://hl7.org/fhir/conceptmap-operation-closure.html)

### Create expression repository <a href="#id-5.4.2expressionrepositorywithhl7fhir-createexpressionrepository" id="id-5.4.2expressionrepositorywithhl7fhir-createexpressionrepository"></a>

Creating an expression repository using a FHIR Terminology Server involves the creation of the following structures:

* A [CodeSystem supplement](https://www.hl7.org/fhir/codesystem.html#supplements) (*expRep*): This functions as the actual expression repository and is used to hold the expressions
* A [CodeSystem](https://www.hl7.org/fhir/codesystem.html#4.8) (*expId*): This code system is used to hold the unique expression identifiers
* A [ConceptMap](https://www.hl7.org/fhir/conceptmap.html#4.10): This is used to map between the expressions in the expRep CodeSystem supplement and the expId CodeSystem. The ConceptMap enables the translation of expressions to (and from) shorter codes for systems with restricted code lengths

<figure><img src="/files/BqrAVAta18h4yWPYjHjm" alt=""><figcaption><p>Workflow for creating an expression repository within an HL7 FHIR Terminology Server.</p></figcaption></figure>

<table data-full-width="true"><thead><tr><th>Service</th><th>Description</th><th>Input</th></tr></thead><tbody><tr><td><p>Create Code System Supplement</p><p><br></p><p><strong>POST /CodeSystem</strong></p></td><td><p>Create the CodeSystem supplement.<br></p><p>This operation must specify a version URI that uses the snomed.info xsct URI with a specific module but no version.</p><p>This resource must supplement a specific version of a SNOMED CT edition.</p><p>The example supplements the International Edition of SNOMED CT (900000000000207008), version Jan 2023 (20230131).</p></td><td><p>{</p><pre data-overflow="wrap"><code>    "resourceType": "CodeSystem",
    "url": "http://snomed.info/info",
    "version": "http://snomed.info/xsct/11000003104",
    "content": "supplement",
    "supplements" : "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/20230131"
}
</code></pre></td></tr><tr><td><p>Create SNOMED Exp IDs Code System</p><p><br></p><p><strong>POST /CodeSystem</strong></p><p><em>(Only needed if EHR cannot store expressions)</em></p></td><td><p>If needed, create a CodeSystem for expression identifiers.</p><p><br></p><p><br></p></td><td><p></p><pre data-overflow="wrap"><code>{
    "resourceType": "CodeSystem",
    "url": "http://snomed.info/snomed/exp-id/1000003",
    "status": "active",
    "content": "complete"
}
</code></pre><p></p></td></tr><tr><td><p>Create Concept Map for Exp Ids</p><p><br></p><p><strong>POST /ConceptMap</strong><br></p><p><em>(Only needed if EHR cannot store expressions)</em><br></p></td><td>Create the ConceptMap to map expressions in the code system supplement to expression identifiers in the Exp. Ids code system. This will be populated manually.</td><td><p></p><pre data-overflow="wrap"><code>{
        "resourceType": "ConceptMap",
    "url": "http://snomed.info/snomed/exp-id-map",
    "status": "active",
    "source": {
  a0  a0  a0  a0"sourceUri": "http://snomed.info/xsct/1234007?fhir_vs"},
    "target": {
  a0  a0  a0  a0"targetUri": "http://snomed.info/snomed/exp-id/1101234?fhir_vs"}
  }
</code></pre><p></p></td></tr></tbody></table>

### Get repository details <a href="#id-5.4.2expressionrepositorywithhl7fhir-getrepositorydetails" id="id-5.4.2expressionrepositorywithhl7fhir-getrepositorydetails"></a>

<table data-full-width="true"><thead><tr><th>Service</th><th>Description</th><th>Input</th></tr></thead><tbody><tr><td><strong>GET /CodeSystem/{id}</strong></td><td>Get the details of the Code System using the provided ID; it is the same operation for the supplement or the Exp. IDs code system.</td><td><pre data-overflow="wrap"><code>Code System ID, provided in the response of the code system creation
</code></pre></td></tr></tbody></table>

### Add expression <a href="#id-5.4.2expressionrepositorywithhl7fhir-addexpression" id="id-5.4.2expressionrepositorywithhl7fhir-addexpression"></a>

<table data-full-width="true"><thead><tr><th>Service</th><th>Description</th><th>Input</th></tr></thead><tbody><tr><td><strong>PATCH /CodeSystem/{id}</strong></td><td><p>Adds an expression in the Code System Supplement using a patch operation.</p><p>The display value can be generated from the expression, or the expression itself could be used in this field.</p><p>This operation should run validation on the expression being inserted into the supplement.</p></td><td><pre data-overflow="wrap"><code>[
  { 
    "op": "add", 
    "path": "/concept", 
    "value": {
      "code": "359817006 |Closed fracture of hip (disorder)| : 
       272741003 |Laterality (attribute)| = 182353008 |Side (qualifier value)|",
      "display": "Right closed fracture of hip"
    } 
  }
]
</code></pre></td></tr></tbody></table>

(Source: <https://fhirblog.com/2019/08/13/updating-a-resource-using-patch/>)

### Lookup expression <a href="#id-5.4.2expressionrepositorywithhl7fhir-lookupexpression" id="id-5.4.2expressionrepositorywithhl7fhir-lookupexpression"></a>

<table data-full-width="true"><thead><tr><th width="430.1328125">Service</th><th width="127.39453125">Description</th><th width="349.07421875">Input</th><th>Output</th></tr></thead><tbody><tr><td><p><strong>GET /CodeSystem/{supplementId}/$lookup?code={<code>CTU</code>}</strong></p><p><strong>GET /CodeSystem//$lookup?<code>system={versionUri}&#x26;code={CTU}</code></strong></p></td><td>Lookup Expression in the supplement</td><td><ul><li>versionUri</li><li>CTU: close-to-user expression</li></ul></td><td><br></td></tr><tr><td><p><strong>GET /ConceptMap/{<code>snomed-exp-id-map}/$translate?system={versionUri}&#x26;code={CTU}</code></strong></p><p><strong><code>Example</code></strong></p><p><em>GET /ConceptMap/<code>snomed-exp-id-map/$translate?system=http://snomed.info/xsct/1234007</code></em><br><em><code>&#x26;code=87971000:272741003=7771000</code></em></p></td><td>Lookup Expression Identifier from Expression</td><td><ul><li>versionUri</li><li>CTU: close-to-user expression</li></ul><p><br></p></td><td><br></td></tr><tr><td><p><strong>GET /ConceptMap/{<code>snomed-exp-id-map}/$translate?</code></strong><br><strong><code>reverse=true&#x26;system={versionUri}&#x26;code={expId}</code></strong></p><p><strong><code>Example</code></strong></p><p><em>GET /ConceptMap/<code>snomed-exp-id-map/$translate?</code></em><br><em><code>reverse=true&#x26;system=http://snomed.info/snomed/exp-id/1101234&#x26;code=101101234165</code></em></p></td><td>Lookup Expression from Expression Identifier</td><td><ul><li>versionUri</li><li>expId: expression identifier as defined pr. implementation</li></ul></td><td><br></td></tr></tbody></table>

### Search for expression <a href="#id-5.4.2expressionrepositorywithhl7fhir-searchforexpression" id="id-5.4.2expressionrepositorywithhl7fhir-searchforexpression"></a>

Use an implicit value set with ECL.

### Get display term <a href="#id-5.4.2expressionrepositorywithhl7fhir-getdisplayterm" id="id-5.4.2expressionrepositorywithhl7fhir-getdisplayterm"></a>

A display term should be returned in the response of the lookup operation. The display term may be generated in a very simple way by just concatenating.

### Create Classifiable Form <a href="#id-5.4.2expressionrepositorywithhl7fhir-createclassifiableform" id="id-5.4.2expressionrepositorywithhl7fhir-createclassifiableform"></a>

This should happen when the expression is inserted into the code system.

### Create Necessary Normal Form <a href="#id-5.4.2expressionrepositorywithhl7fhir-createnecessarynormalform" id="id-5.4.2expressionrepositorywithhl7fhir-createnecessarynormalform"></a>

This should happen when the expression is inserted into the code system.

### Subsumption <a href="#id-5.4.2expressionrepositorywithhl7fhir-subsumption" id="id-5.4.2expressionrepositorywithhl7fhir-subsumption"></a>

<table data-full-width="true"><thead><tr><th>Service</th><th>Description</th><th>Input</th></tr></thead><tbody><tr><td><p>Expression subsumption test</p><p><strong>GET /CodeSystem/$subsumes</strong></p></td><td>Test the subsumption between a pair of expressions or an expression and a code.<br></td><td><p>{</p><pre data-overflow="wrap"><code>    "resourceType": "CodeSystem",
</code></pre></td></tr></tbody></table>

<a href="https://docs.google.com/forms/d/e/1FAIpQLScTmbZIf0UEQwYDkY27EEWBkaiYkHSbR0_9DmFrMLXoQLyL7Q/viewform?usp=pp_url&#x26;entry.1767247133=Postcoordination+Guide&#x26;entry.670899847=Expression%20Repository%20with%20HL7%20FHIR" class="button primary">Provide Feedback</a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-postcoordination-guide/expressions-in-a-terminology-server/implementation-examples/expression-repository-with-hl7-fhir.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.