# Terminology Services Design

*Interacting with a terminology server is done via a set of supported services designed to meet key user requirements. The following pages provide details about the services required for a terminology server supporting postcoordination. Please note that the services designed to support an expression repository will often be used in conjunction with the services available to access precoordinated content. The general services of a SNOMED CT-enabled terminology server can be found in the* [*Terminology Services Guide*](https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/t4wRQcj6gyQPunraJrP0/)*.*

## Create Expression Repository

#### Objective

The objective of services for creating an expression repository is to set up the structures of the expression repository and provide an 'empty' expression repository.

#### Description

To set up an expression repository, it requires a terminology server with access to a SNOMED CT versioned edition. This is important because all concepts referenced by an expression must be interpreted in the context of a specific SNOMED CT Edition. To support processing of the expressions, access to information about the source concepts and to the particular version of the MRCM that is encoded within the version of the substrate is needed.

Note the MRCM does not change very frequently: several different consecutive versions of the substrate will contain different sets of concepts and their stated relationships, but may contain essentially the same MRCM content and version.

<figure><img src="https://2240938627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FusjN9isxKh4cLDTFopLg%2Fuploads%2FHJgcNsQThy1dBlI6Yr01%2Fimage.png?alt=media&#x26;token=dfaaab73-2b55-43c0-8fc1-dc6925a333ca" alt=""><figcaption></figcaption></figure>

In addition to specifying the 'substrate' of the expression repository, it is important to specify the primary language, or languages, that should function as the default language for the repository. This is important to support the display of terms associated with the expressions. For the language configuration, it is recommended to specify which language reference set(s), available in the substrate, should be used as the default.

#### Summary

<table><thead><tr><th width="121.6640625">Service</th><th width="147.5078125">Description</th><th>Input Parameters</th><th>Response</th></tr></thead><tbody><tr><td><strong>Create expression repository</strong></td><td>Creates a new repository</td><td><p>- <strong>substrate</strong> : the base edition for this repository</p><p>- <strong>languages</strong> (0-*): pairs of language refsetIds + language codes used to generate descriptions (optional)</p></td><td><p><strong>Success:</strong> True, with identifier of the generated repository</p><p><strong>Failure:</strong> False, with appropriate error message</p></td></tr></tbody></table>

## Get Details of an Expression Repository <a href="#title-text" id="title-text"></a>

#### Objective <a href="#id-5.2.2getdetailsofanexpressionrepository-objective" id="id-5.2.2getdetailsofanexpressionrepository-objective"></a>

To retrieve details about a generated expression repository. The details of the repository can be used when referring to the content of this specific expression repository, e.g. for adding and updating content in the expression repository.

#### Summary <a href="#id-5.2.2getdetailsofanexpressionrepository-summary" id="id-5.2.2getdetailsofanexpressionrepository-summary"></a>

| Service                                        | Description                  | Input Parameters                                                                                                                                          | Response                                                                                                                                                    |
| ---------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Get details about an expression repository** | Gets details of a repository | <p><strong>- substrate:</strong> the base edition for this repository</p><p><strong>- repId:</strong> a unique reference to the expression repository</p> | <p><strong>Success:</strong> Return details of the selected expression repository and dependencies</p><p><strong>Failure:</strong> Return error message</p> |

## Update Expression Repository

#### Objective

The objective of a service to update an expression repository is to support the ongoing maintenance and alignment with new versions of SNOMED CT used as the substrate for the expression repository.

#### Description

Updating an expression repository involves changing the substrate of an expression repository to a new, or another, substrate. Often, the new substrate will be to a new version of the expression repository substrate. Any changes made to the terminology between the SNOMED CT version being the current substrate and the SNOMED CT version that will become the new substrate may impact the content of the expression repository. For example, if a concept included in one of the expressions stored in the repository has been made inactive, the expression is no longer valid after applying the new substrate. Or, if concept model rules stated in the Machine Readable Concept model have been modified, expressions may no longer be concept model compliant.

The services for updating of the expression repository needs, therefore, need to support

1. Validate the CTU of all existing expressions against the new substrate
2. Resolve any validation issues, e.g. by
   1. replacing inactive concepts with proper replacements
   2. adjusting expression to conform to the MRCM
3. Transform the updated expressions (update the classifiable form expressions)
4. Classify the expression repository against the new substrate, and where relevant, generate new versions of the necessary normal form

#### Summary

<table><thead><tr><th width="127.578125">Service</th><th width="170.12109375">Description</th><th width="273.4296875">Input Parameters</th><th>Response</th></tr></thead><tbody><tr><td><strong>Update expression repository</strong></td><td>Creates a new version of a specific repository</td><td><p>- <strong>substrate</strong> : the new base edition for this repository</p><p>- <strong>repId</strong> : identifier of the repository to be updated</p><p><strong>- languages</strong> (0-*): pairs of language refsetIds + language codes used to generate descriptions (optional)</p></td><td><p><strong>Success:</strong> True</p><p><strong>Failure:</strong> False, with appropriate error message</p></td></tr></tbody></table>

## Add Expression

#### Objective

The objective of the services described in this page is to enable the addition of a new expression in the expression repository.

#### Description

Adding an expression to an expression repository requires the validation of the expression and the storage of the expression as it has been entered by the user with the additional data and expression forms that are needed for subsequent access and use.

#### Workflow

The logical process of the add expression service is illustrated in the diagram below.

<figure><img src="https://2240938627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FusjN9isxKh4cLDTFopLg%2Fuploads%2FHDSIFQfFW8fftZhfbwIp%2Fimage.png?alt=media&#x26;token=a2604eda-e1a7-40cd-965f-d13128bc35df" alt=""><figcaption><p>Workflow for the add expression service</p></figcaption></figure>

#### Summary

<table><thead><tr><th width="114.859375">Service</th><th width="161.23046875">Description</th><th width="210.421875">Input Parameters</th><th>Response</th></tr></thead><tbody><tr><td><strong>Add expression</strong></td><td>Adds a new postcoordinated expression to the expression repository</td><td><p><strong>- substrate:</strong> the base edition for this repository</p><p>- <strong>repId</strong>: a unique reference to the expression repository - <strong>CTU</strong>: Close to user form expression</p></td><td><p><strong>Success:</strong> Return data associated with the expression</p><ul><li>Expression identifier, if generated</li><li>CTU expression</li><li>CF expression, if generated</li><li>NNF relationships, if generated</li></ul><p><strong>Failure:</strong> <em>"Expression not added"</em> plus an indication of the reason (e.g. transformation issue, classification issue, term generation issue)</p></td></tr></tbody></table>

## Validate and Transform Expression

#### Objective

The objective of this service is to validate a CTU expression and transform it into a classifiable form (CF) which can be used as input to the Description Logic classifier.

#### Description

This service involves both the validation and transformation of a CTU expression. Three types of validation are required, including syntactic validation, content validation, and MRCM validation. For expressions not fully compliant with the MRCM, a transformation is required to generate the classifiable form.

#### Syntactic Validation

The syntactic validation is performed to determine if the expression conforms to the SNOMED CT compositional grammar syntax (see [Compositional Grammar - Specification and Guide](http://snomed.org/scg) section Parsing).

Please refer to the [Compositional Grammar - Specification and Guide](https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/VgpC90r7t9DyATri97GG/) (section Validating) for more details on the validation of expression, and the [Machine Readable Concept Model](https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/wLJPOzgAQsSAYr6nhvCl/) for details on the computer processable concept model rules.

#### Content Validation

The content validation is performed to determine if all concept references included in the expression exists and are active in the version and edition of SNOMED CT which is the substrate for the given expression repository.

#### MRCM Validation

The MRCM validation is performed to determine if the expression complies to the concept model rules as expressed in the SNOMED CT Concept Model and specified by the machine readable concept model (the version of the MRCM applying to the version and edition of SNOMED CT which is the substrate for the given expression repository)

An expression that *does not* conform to the *concept model* cannot be relied upon to correctly classify. Therefore, it cannot be reliably tested for subsumption by another *concept* or inclusion in (or exclusion from) the results of an expression constraint or analytics query.

Specific terminology services required to support MRCM validation are described in the general Terminology Services Guide here: SNOMED CT concept model

#### Transformation

Expressions that are fully compliant with the Machine Readable Concept will not need a transformation to be represented in the classifiable form. This means that for fully MRCM compliant expressions the close-to-user form and the classifiable form of the expression are the same.

An expression may be invalid when tested against the concept model but may contain refinements that would be valid if correctly structured. There are several situations where predictable structural adjustments enable a valid expression to be constructed from an informal expression that does not fully conform to the concept model.

Examples include:

* Moving a loose attribute to an attribute group in which it is valid
* Moving a loose attribute so it provides a nested refinement to the value of another attribute

A loose attribute is an attribute that is included in the refinement of an expression without being placed in a group, although the concept model rules require it to be grouped.

The extent to which a terminology server supports the transformation of non-MRCM compliant expressions into MRCM-compliant expressions may vary between terminology servers. Each terminology server should, therefore, clearly state the level of transformations supported for expressions that are not fully MRCM compliant. A recommended practice for this it to support an API call by which it is possible to determine the transformation level. For more detail on these levels, see [Implementation](https://github.com/SNOMED-Documents/snomed-postcoordination-guide/blob/main/expressions-in-a-terminology-server/design/broken-reference/README.md)

#### Workflow

The logical process of the service to transform and validate an expression is illustrated in the diagram below.

<figure><img src="https://2240938627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FusjN9isxKh4cLDTFopLg%2Fuploads%2FR5MSi3iYkqlFG9R2zAlZ%2Fimage.png?alt=media&#x26;token=4fdb80e1-340e-4ee7-992d-2e454443c29a" alt=""><figcaption><p>Workflow for the validate and transform expression</p></figcaption></figure>

**Summary**

| Service                               | Description                                                                                                                                                                                   | Input Parameters                                                                                       | Response                                                                                                      |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **Validate and transform expression** | Check that the CTU is syntactically valid and conforms to the concept model rules, or allowed rules for postcoordination. Transforms the close-to-user form expression to a classifiable form | **- id:** a unique reference to the expression repository - **expId**: CTU expression or expression id | <p><strong>Success:</strong> True</p><p><strong>Failure:</strong> False, with validation error indication</p> |

## Generate Necessary Normal Form <a href="#id-5.2.2.6-generate-necessary-normal-form" id="id-5.2.2.6-generate-necessary-normal-form"></a>

**Objective**

The objective of this service is to support classification and Necessary Normal Form generation

**Related Use Cases**

Classification is required to enable the following use case: Query Expressions

**Description**

To enable postcoordinated expressions to be queried in the same way as pre-coordinated SNOMED CT concepts, the necessary normal form of the expression is required, as illustrated in the diagram below.

**Workflow**

<figure><img src="https://2240938627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FusjN9isxKh4cLDTFopLg%2Fuploads%2FkygQbhNeKAbpKlvRdSZs%2Fimage.png?alt=media&#x26;token=104135aa-dde8-4ddc-bf4a-3ae9bb21085c" alt=""><figcaption><p>Workflow for the service generating the Necessary Normal Form Expression</p></figcaption></figure>

**Summary**

| Service          | Description                                                                              | Input Parameters                                                                         | Response                                                                                                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Generate NNF** | Classifies the expression (CF) and generates the necessary normal form of the expression | **- repId:** a unique reference to the expression repository **- CF:** Classifiable form | <p><strong>Success:</strong> As a minimum, returns the necessary normal form of the expression</p><p><strong>Failure:</strong> Display an appropriate error message</p> |

## Lookup Expression <a href="#id-5.2.7-lookup-expression" id="id-5.2.7-lookup-expression"></a>

**Objective**

The objective of this service is to get data associated with an identified expression.

**Description**

Services for retrieving data associated with an expression rely on an input pointing to the expression of interest. For this purpose, a unique identifier associated with the expression within an expression repository should be input to this service. If the CTU of the expression itself is used to uniquely identify the expression, this will be used for the lookup. If multiple versions of the expression exists, the service will return the most recent version of the expression.

**Workflow**

<figure><img src="https://2240938627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FusjN9isxKh4cLDTFopLg%2Fuploads%2F31gq6fL9vqFTZha2DcJp%2Fimage.png?alt=media&#x26;token=81dd49fd-4516-47e2-bb5b-5f1537a7a45e" alt=""><figcaption><p><br>Workflow for the expression Lookup service</p></figcaption></figure>

## Search Expression

**Objective**

The objective of this service is to enable text-based searching for expressions in the expression repository.

**Description**

As specified in [Expression Repository Requirements](https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/usjN9isxKh4cLDTFopLg/~/changes/27/~/revisions/BrlSrjPF4gRqXeA8MhbU/5-expressions-in-a-terminology-server/5.1-requirements/5.1.1-expression-repository-requirements), an expression repository includes the canonical form of the stored expressions. The canonical form excludes any terms associated with the referenced concepts.Consider storing a term associated with the expression to aid searching.Please note that this guide does not include guidance on the storage of a human-readable term for expressions, but it recommends implementing services to automatically generate a display term. Some implementations may choose to store an autogenerated display term for each expression in the repository as part of adding the expression. This may be chosen to support easy lookup of the terms associated with the expressions to support services for searching.

**Summary**

| Service                   | Description             | Input Parameters                                                                                                                                                                                                                                                   | Response                                                                                                                                                                                                                                                                               |
| ------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Search for expression** | Find expression by term | <p><strong>- repId:</strong> a unique reference to the expression repository</p><p>- <strong>Search string</strong></p><p>- <strong>Search technique</strong> option (if required)</p><p><strong>- Search filtering</strong> or sorting options (if supported)</p> | <p><strong>Success:</strong> A collection of matching terms each of which is linked to an expression within the expression repository.</p><ul><li>Display term (generated)</li><li>Expression identifier</li></ul><p><strong>Failure:</strong> Return an appropriate error message</p> |

## Get Display Term <a href="#id-5.2.2.9-get-display-term" id="id-5.2.2.9-get-display-term"></a>

**Objective**

The objective of services to get a display term for an expression, is to support the automatic generation of a term that can be used for the human-readable representation of the term, e.g for display or exchange.

**Description**

Three different approaches to automatically creating display terms for postcoordinated expressions is presented, ranging from the simplest to the most complex.

1. Replace concept identifiers with terms
2. Apply simple term rules
3. Apply description templates and rules

Please refer to [Appendix A: Techniques for Autogenerating Display Terms](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-postcoordination-guide/appendixes/appendix-a-techniques-for-autogenerating-display-terms) for details on these approaches. Please note that alternative approaches may be equally valid for this task.

**Summary**

| Service                     | Description                                                                                           | Input parameters                                                                                                                                                                                                                                                                                                                                         | Response                                                                                            |
| --------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Get term for expression** | Gets an autogenerated term for the expression using the technique supported by the terminology server | <p><strong>- substrate:</strong> the base edition for this repository<strong>- id:</strong> a unique reference to the expression repository</p><p><strong>- expression:</strong> a unique reference to the expression</p><p><strong>- technique:</strong> if multiple techniques for generating terms exist, the technique to apply may be indicated</p> | **Success:** Return the generated display term(s)​**Failure:** Display an appropriate error message |

## Query Expression <a href="#id-5.2.2.10-query-expression" id="id-5.2.2.10-query-expression"></a>

**Objective**

A terminology server should support services that are required for patient- and population-oriented data retrieval and analytics tasks. The objective of expression query services is to enable subsumption testing between expressions and enable selective retrieval of postcoordinated expressions satisfying stated criteria.

**Description**

***Subsumption*** ***Testing***&#x57;hen expressions are used, it is necessary to determine whether the meaning of a particular expression is a subtype of a specified concept or more generally is subsumed by a particular expression constraint. The terminology services required are similar to those described for testing concepts in sections 4.5 Get and Test Concept Subtypes and Supertypes.

***Selective Retrieval***

As for precoordinated concepts, expressions may be queried based on the inferred properties derived from the classification process. Expression constraints may be formulated and executed against the expression repository and the associated substrate to return both precoordinated concepts and expressions that match the specified constraint, see [Service Requirements](https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/usjN9isxKh4cLDTFopLg/~/changes/27/~/revisions/BrlSrjPF4gRqXeA8MhbU/5-expressions-in-a-terminology-server/5.1-requirements/5.1.2-terminology-services-requirements).

**Summary**

| Service              | Description                                                                        | Input parameters                                                                                                                                                                                                                                                              | Response                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Query expression** | Subsumption - check if there is a subsumption relationship between two expressions | <p><strong>- repId:</strong> a unique reference to the expression repository</p><p><strong>- source:</strong> CTU expression, expression id, or concept id</p><p><strong>- target:</strong> CTU expression, expression id, or concept id</p>                                  | <p><strong>Success:</strong> Return data to inform which of the following outcomes are true:</p><ul><li>Source is a subtype of target</li><li>Target is a subtype of source</li><li>No subsumption relationship between source and target</li></ul><p><strong>Failure:</strong> Display an appropriate error message</p>                                                                                                                                                                  |
| **Query expression** | Get concepts and expressions that conform to an expression constraint              | <p><strong>- repId:</strong> a unique reference to the expression repository</p><p><strong>- ecl:</strong> an expression constraint complying to the <a href="https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/sOJBD7YbxAy9bD1Ko9L9/">Expression Constraint Language</a>​</p> | **Success:** Return a set of conceptIds and CTU expressions that conform to the expression constraintOptionally additional information such as the fully specified name or preferred term of each concept included in the expansion plus generated terms for included expressions​**Failure:** Return error message if expression constraint contains syntax errors​Return error message if any concept identifiers in the expression constraint are not present in the specified edition |

<a href="https://docs.google.com/forms/d/e/1FAIpQLScTmbZIf0UEQwYDkY27EEWBkaiYkHSbR0_9DmFrMLXoQLyL7Q/viewform?usp=pp_url&#x26;entry.1767247133=Postcoordination+Guide&#x26;entry.670899847=Terminology%20Services%20Design" 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/design/terminology-services-design.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.