# Semantic Standardization Module [EAP](/content/docs/hdp_product/maturity_model.html)

**Early Access Feature:** This module is in Early Access status and subject to change.

The Semantic Standardization Module enables automated semantic enrichment of FHIR resources by standardizing `CodeableConcept` elements with preferred terminologies.

Enrichment is accomplished when fragmented data is standardized, structured, made computable data

- Records are standardized to a consistent data model (FHIR) → syntactic standardization
- Data values are standardized to standard terminologies (LOINC, SNOMED) → semantic standardization
- Data values meet specified data quality requirements → data validation

Dependency on Persistence is to resolve FHIR version only. No data is persisted with just the Semantic Standardization Module

## Overview

The Semantic Standardization Module processes FHIR resources to enhance semantic interoperability by:

- **Extracting**`CodeableConcept`elements using FHIRPath expressions.

- FHIR resources with `CodeableConcept` elements will be evaluated for standardization.
  - Current release support is limited to the most clinically significate code on each resource.
- **Validating**existing codes against defined standards

- Validation is simple to acknowledge what was provided is correct.
  - No action is taken if `CodeableConcept``coding` provided is accurate.
- **Enriching**resources with standardized terminology mappings

- Adding a well-formed coding with `system`, `code` and `display` given

- the text description of the `CodeableConcept` or
    - the display field provided in a `CodeableConcept``coding`
- **Correcting**code displays and system references

- Add new coding when inaccurate system url's and nonstandard code displays are provided
  - Add new coding when a system/code has been retired/replaced
- **Translating**codes between terminology systems

- ex. Adds RXNORM coding when provided NDC.

## Architecture

## Module Configuration

**Web Admin Console Configuration**

1. Navigate to **Configuration** → **Module Config**
2. Select **Add Module** dropdown
3. Choose **Semantic Standardization**
4. Select target **Node**
5. Click **Add**

**Configuration Parameters**

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| **Base URL** | String | `http://localhost:8080` | Terminology provider service endpoint |
| **Confidence Level** | String | `0.80` | Minimum confidence threshold for mappings |
| **Configuration Text** | JSON | Empty config | JSON mapping configuration (Advanced) |
| **Configuration File** | File Path | - | Path to JSON mapping file (Advanced) |
| **FHIR Version** | Enum | R4 | Supported FHIR version |

Only FHIR R4 is currently supported.

**Property-Based Configuration**
if you are running in `node.propertysource=PROPERTIES` mode, you would add the following line to your `cdr-config-Master.properties` file:

```properties
module.[MODULE_ID].config.base_url=http://localhost:8080
module.[MODULE_ID].config.min_confidence=0.85
module.[MODULE_ID].config.fhir_version=R4
```

Copy

## Mapping Configuration

The Semantic Standardization module uses a JSON configuration to define which FHIR resources and elements that should be processed.

**Configuration Structure****Root Level**

| Field | Type | Description |
| --- | --- | --- |
| `description` | String | Human-readable configuration description |
| `version` | String | Configuration version for source control management only |
| `fhirVersion` | String | Fhir version supported by the configuration |
| `resourceMappings` | Array | Array of resource mapping definitions (only setting that has impact at runtime) |

```json
{
  "description": "Configuration description",
  "version": "1.0.0",
  "fhirVersion": "4.0.1",
  "resourceMappings": []
}
```

Copy

The description, version and fhirVersion are currently only provided of the file creator/maintainer.

The resourceMappings are used by the system to determine the  [FHIR Path](https://hl7.org/fhir/R4/fhirpath.html) to the elements of type `CodeableConcept` as well as which standardization features of Semantic Standardization will be executed.

The FHIR Path is important when element's name or location change between versions of the FHIR Standard.

**Resource Mapping**

| Field | Type | Description |
| --- | --- | --- |
| `resourceType` | String | FHIR resource type (e.g., "Condition") |
| `codeableConceptMapping` | Array | Element-specific mapping configurations |

The `resourceMapping` is a JSON array that allows configuration specific to each FHIR Resource.

The `resourceMapping` has two main component the `resourceType` and the `codeableConceptMapping`

- `resourceType` is a FHIR resource type. `Condition` as an example
- `codeableConceptMapping` is an Array for additional configuration discussed below

```json
{
  "resourceType": "Condition",
  "codeableConceptMapping": []
}
```

Copy

**CodeableConcept Mapping**

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `fhirPath` | String | - | FHIRPath expression to locate the element |
| `targetOntologyUrl` | String | - | Preferred terminology system URL |
| `correctCode` | Boolean | false | Add corrected coding for same system |
| `correctDisplay` | Boolean | false | Add corrected display text |
| `translate` | Boolean | false | Add codings from target terminology |
| `textToCoding` | Boolean | false | Generate codes from CodeableConcept.text |

The `codeableConceptMapping` is a JSON array that allows configuration specific to each FHIR Resource

- `fhirPath` is a FHIRPath. `code` as an example
- `targetOntologyUrl` is the url of the standard ontology. `http://snomed.info/sct` as an example
- `correctCode` is a boolean flag that will direct the system to correct code values is true
- `correctDisplay` is a boolean flag that will direct the system to correct display values if true
- `translate` is a boolean flag that will direct the system to add codings from the Code system referenced in the targetOntologyUrl if true
- `textToCoding` is a boolean flag that will evaluate the text and display elements of the `CodeableConcept` to add codings if true

The flags provide fine grain control over actions taken by Semantic Standardization module

```json
{
  "fhirPath": "code",
  "targetOntologyUrl": "http://snomed.info/sct",
  "correctCode": true,
  "correctDisplay": true,
  "translate": true,
  "textToCoding": true
}
```

Copy

**Example Configuration**
This example configuration can be used as a starting point for an implementation and referenced in the module configuration

- File Path to JSON mapping file (Advanced)

```json
{
	"description": "Configuration for mapping FHIR resources to their respective CodeableConcepts using FHIRPath. Each potential path is explicitly paired with a target terminology URL and processing options",
	"version": "1.0.0",
	"fhirVersion": "4.0.1",
	"resourceMappings": [\
		{\
			"resourceType": "AdverseEvent",\
			"codeableConceptMapping": [\
				{ "fhirPath": "substance.code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": false, "correctDisplay": false, "translate": false, "textToCoding": false }\
			]\
		},\
		{\
			"resourceType": "AllergyIntolerance",\
			"codeableConceptMapping": [\
				{ "fhirPath": "code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "Condition",\
			"codeableConceptMapping": [\
				{ "fhirPath": "code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "Device",\
			"codeableConceptMapping": [\
				{ "fhirPath": "type", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "Immunization",\
			"codeableConceptMapping": [\
				{ "fhirPath": "vaccineCode", "targetOntologyUrl": "http://hl7.org/fhir/sid/cvx", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "MedicationAdministration",\
			"codeableConceptMapping": [\
				{ "fhirPath": "medication.as(CodeableConcept)", "targetOntologyUrl": "http://www.nlm.nih.gov/research/umls/rxnorm", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "MedicationDispense",\
			"codeableConceptMapping": [\
				{ "fhirPath": "medication.as(CodeableConcept)", "targetOntologyUrl": "http://www.nlm.nih.gov/research/umls/rxnorm", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "MedicationRequest",\
			"codeableConceptMapping": [\
				{ "fhirPath": "medication.as(CodeableConcept)", "targetOntologyUrl": "http://www.nlm.nih.gov/research/umls/rxnorm", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "MedicationStatement",\
			"codeableConceptMapping": [\
				{ "fhirPath": "medication.as(CodeableConcept)", "targetOntologyUrl": "http://www.nlm.nih.gov/research/umls/rxnorm", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "Observation",\
			"codeableConceptMapping": [\
				{ "fhirPath": "code", "targetOntologyUrl": "http://loinc.org", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "Procedure",\
			"codeableConceptMapping": [\
				{ "fhirPath": "code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		},\
		{\
			"resourceType": "Substance",\
			"codeableConceptMapping": [\
				{ "fhirPath": "code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }\
			]\
		}\
	]
}
```

Copy

## FHIR Operations

**$semantic-uplift Operation**
The module provides a `$semantic-uplift` operation for on-demand semantic enhancement of FHIR resources.

This operation requires the  [FHIR\_SEMANTIC\_UPLIFT](/content/docs/security/roles_and_permissions.html#FHIR_SEMANTIC_UPLIFT/index.html) permission.

**Usage**

```http
POST [base]/[ResourceType]/$semantic-uplift
```

Copy

The operation processes the resource(s) according to the configured mapping rules and returns semantically enhanced versions.

## Camel Integration

The module provides a Camel processor for integration with data processing workflows:

```xml
<to uri="semantic-std-processor"/>
```

Copy

See [Camel Overview documentation page](/content/docs/camel/camel_module_overview.html).

## Supported FHIR Resources

The module supports semantic standardization for any FHIR resource containing `CodeableConcept` elements, including:

- **AdverseEvent** \- substance.code
- **AllergyIntolerance** \- code
- **Condition** \- code
- **Device** \- type
- **Immunization** \- vaccineCode
- **Observation** \- code
- **MedicationAdministration** \- medication
- **MedicationDispense** \- medication
- **MedicationRequest** \- medication
- **MedicationStatement** \- medication
- **Procedure** \- code
- **Substance** \- code

## Performance Considerations

- Results are cached to improve performance for repeated mappings (restart of the module will clear cache)
- Confidence thresholds are used by the terminology provider to results. The lower the confidence could potential add lower-quality mappings

## Troubleshooting

**Common Issues**
**Module fails to start**

- Verify terminology provider URL is accessible
- Check network connectivity to external services
- Review configuration syntax in mapping JSON

**Poor mapping quality**

- Adjust confidence level threshold
- Review terminology provider configuration
- Validate input data quality

**Performance issues**

- Enable result caching
- Increase network timeouts
- Consider batch processing for large volumes

Semantic Standardization Module

Semantic Standardization

[Semantic Standardization Module](/content/docs/semantic_std/semantic_std.html)
[West Coast Informatics (WCI) Provider](/content/docs/semantic_std/semantic_std_provider_wci.html)

[West Coast Informatics (WCI) Provider](/content/docs/semantic_std/semantic_std_provider_wci.html)