FHIR ConceptMap/$translate across OMOP vocabularies

Overview

Translates codes between vocabularies using OMOP Maps to relationships. Supports both forward (source code to OMOP standard) and reverse (OMOP concept to source code) translation. Key R4/R5 difference: R4 responses use equivalence, R5/R6 use relationship.

Forward Translation

Translate a source code to its OMOP standard equivalent:

curl "https://fhir.omophub.com/fhir/r4/ConceptMap/\$translate?\
sourceCode=E11.9&\
system=http://hl7.org/fhir/sid/icd-10-cm&\
targetSystem=https://fhir-terminology.ohdsi.org" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST with sourceCoding

curl -X POST "https://fhir.omophub.com/fhir/r4/ConceptMap/\$translate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      {
        "name": "sourceCoding",
        "valueCoding": {
          "system": "http://hl7.org/fhir/sid/icd-10-cm",
          "code": "E11.9"
        }
      },
      { "name": "targetSystem", "valueUri": "https://fhir-terminology.ohdsi.org" }
    ]
  }'

Reverse Translation

Look up the source code for an OMOP concept:

curl "https://fhir.omophub.com/fhir/r4/ConceptMap/\$translate?\
targetCode=201826&\
system=https://fhir-terminology.ohdsi.org" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

Forward

Parameter	Type	Required	Description
`sourceCode`	code	Yes*	Source code to translate
`sourceCoding`	Coding	Yes*	Alternative: Coding with system + code
`system`	uri	Yes*	Source code system URI (required with `sourceCode`, included in `sourceCoding`)
`targetSystem`	uri	No	Target code system (defaults to OMOP unified)
`url`	uri	No	Canonical URL of a specific FHIR-to-OMOP IG ConceptMap to translate through (e.g. `http://hl7.org/fhir/uv/omop/ConceptMap/ConditionConcepts`). When the code is present in that map, its target is returned; otherwise translation falls back to the default system-based resolution.

*Provide either sourceCode + system or sourceCoding.

Reverse

Parameter	Type	Required	Description
`targetCode`	code	Yes*	OMOP concept_id to reverse-lookup
`targetCoding`	Coding	Yes*	Alternative: Coding with system + code
`system`	uri	No	The code system of the target concept (use `https://fhir-terminology.ohdsi.org` for OMOP unified, or a vocabulary-specific URI to filter)

*Provide either targetCode or targetCoding.

Response (R4)

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "result", "valueBoolean": true },
    {
      "name": "match",
      "part": [
        { "name": "equivalence", "valueCode": "equivalent" },
        {
          "name": "concept",
          "valueCoding": {
            "system": "https://fhir-terminology.ohdsi.org",
            "code": "201826",
            "display": "Type 2 diabetes mellitus"
          }
        },
        {
          "name": "product",
          "part": [
            {
              "name": "property",
              "valueUri": "http://omophub.com/fhir/property/domain-id"
            },
            { "name": "value", "valueString": "Condition" }
          ]
        },
        {
          "name": "product",
          "part": [
            {
              "name": "property",
              "valueUri": "http://omophub.com/fhir/property/target-table"
            },
            { "name": "value", "valueString": "condition_occurrence" }
          ]
        }
      ]
    }
  ]
}

The target-table product property is OMOPHub-exclusive. It tells ETL developers exactly which OMOP CDM table the translated concept belongs to.

$translate returns both Maps to and Maps to value targets. The latter decomposes composite concepts into a value concept (HL7 FHIR-to-OMOP IG Value-as-Concept pattern) — e.g. SNOMED “Allergy to penicillin” yields an “Allergy to drug” match (Maps to) and a “Penicillin G” match (Maps to value). Each match carries an OMOPHub-exclusive omop-relationship product (Maps to vs Maps to value) so you can route the value concept to value_as_concept_id. Administrative code systems (gender, encounter class, …) translate via the IG’s administrative ConceptMaps.

R5/R6 Difference

On the /fhir/r5/ and /fhir/r6/ endpoints, equivalence is renamed to relationship:

{ "name": "relationship", "valueCode": "equivalent" }

Equivalence Mapping

OMOP Relationship	FHIR Equivalence
Maps to	`equivalent`
Maps to value	`equivalent`
Is a	`wider`
Mapped from	`narrower`
(no mapping)	`unmatched`

​Overview

​Forward Translation

​POST with sourceCoding

​Reverse Translation

​Parameters

​Forward

​Reverse

​Response (R4)

​R5/R6 Difference

​Equivalence Mapping

Overview

Forward Translation

POST with sourceCoding

Reverse Translation

Parameters

Forward

Reverse

Response (R4)

R5/R6 Difference

Equivalence Mapping