FHIR ConceptMap/$translate across OMOP vocabularies

const options = {method: 'GET'};

fetch('https://fhir.omophub.com/fhir/{version}/ConceptMap/$translate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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

const options = {method: 'GET'};

fetch('https://fhir.omophub.com/fhir/{version}/ConceptMap/$translate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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

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.

Contract Parameters

string

default:"r4"

string

OMOP vocabulary release; defaults to the active release.

string

Header alternative to vocab_release; the header takes precedence.

FHIR wire version (r4, r4b, r5, or r6).

string

Forward source code; code is accepted as an alias.

object

Forward source Coding alternative.

string

System for sourceCode, or an optional reverse-result vocabulary filter.

string

R4/R4B target system. targetSystem is the R5/R6 spelling; either alias is accepted.

string

Target ValueSet URI when it identifies a supported system.

string

Concept code for reverse translation.

object

Coding alternative for reverse translation.

string

Optional canonical administrative ConceptMap URL.

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	R4/R4B target code system. Defaults to the OMOP unified system. Use `targetSystem` on R5/R6; either spelling is accepted as a compatibility alias.
`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)

Response Fields

string

Always Parameters.

array

Result and zero or more mapping matches.

string

result or match.

boolean | null

Whether a translation was found.

array

Match parts.

string

Match-part name.

string | null

R4 equivalence or R5/R6 relationship.

object | null

Translated Coding with system, code, and display.

array

OMOPHub product-property name/value parts.

{
  "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 system determines the coding representation in each match. With targetsystem=https://fhir-terminology.ohdsi.org (or with no target system), match.concept contains an OMOP concept_id. With a vocabulary-specific target such as http://snomed.info/sct, it contains that system URI and the vocabulary’s native concept_code. Unknown target systems return an HTTP 400 OperationOutcome; a known system with no mapping returns result: false and no match.

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 Differences

On the /fhir/r5/ and /fhir/r6/ endpoints, the input parameter is named targetSystem instead of R4/R4B’s targetsystem, and equivalence is renamed to relationship in matches:

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

​Contract Parameters

​Forward Translation

​POST with sourceCoding

​Reverse Translation

​Parameters

​Forward

​Reverse

​Response (R4)

​Response Fields

​R5/R6 Differences

​Equivalence Mapping

Overview

Contract Parameters

Forward Translation

POST with sourceCoding

Reverse Translation

Parameters

Forward

Reverse

Response (R4)

Response Fields

R5/R6 Differences

Equivalence Mapping