Semantic Standardization Module EAP

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:

• ExtractingCodeableConceptelements 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.

• Validatingexisting codes against defined standards

• Validation is simple to acknowledge what was provided is correct.

  • No action is taken if CodeableConcept``coding provided is accurate.

• Enrichingresources 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

• Correctingcode 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

• Translatingcodes 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

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:

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

{
  "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 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

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

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

Copy

CodeableConcept Mapping

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

{
  "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)

{
    "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 permission.

Usage

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:

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

Copy

See Camel Overview documentation page.

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 West Coast Informatics (WCI) Provider

West Coast Informatics (WCI) Provider