/
Interactions with the Terminology Service

Interactions with the Terminology Service

Description for how to interact with the terminology service.

 

Extracting Translations from ValueSet and CodeSystem

How to determine, say, Danish translations used in ValueSet? The ValueSet as a resource is likely not to contain a proper, displayable value in Danish as the ValueSet can be defined as include of other ValueSet and/or include entire or partial CodeSystem, and as the display values in the ValueSet are for technical help primarily. Translations, if available, reside in the CodeSystem.

To get translations for at ValueSet, use $expand as follows:

  1. Call $expand on the ValueSet

    1. GET <base-url>/fair/ValueSet/$expand?url=<ValueSet url>&property=designation

  2. Determine the best translation:

    1. Choose a designation with “da” (for Danish) if available, otherwise

    2. Choose display (as the best alternative - this will be in whatever language the concept is defined with)

      1. In the example below, this is the case for code assessment

Example request and response on $expand on topic-type

Request:

GET <base-url>/fhir/ValueSet/$expand?url=http://ehealth.sundhed.dk/vs/topic-type

Response:

{     "resourceType": "ValueSet",     "status": "active", …             {                 "system": "http://hl7.org/fhir/definition-topic",                 "code": "assessment",                 "display": "Assessment"             }, …             {                 "system": "http://ehealth.sundhed.dk/cs/topic-type",                 "code": "self-treatment",                 "display": "Self-treatment",                 "designation": [                     {                         "language": "da",                         "value": "Selvbehandling"                     }                 ]             } …

 

CodeSystems and designations

For supported operations on concept lookups and decomposition, please see the supported operations on CodeSystem at https://www.hl7.org/fhir/R4/codesystem-operations.html . Designations targeted consumers/citizens will eg. contain the following data in the designation:

<designation> <language value="da"></language> <use> <system value="http://terminology.hl7.org/CodeSystem/hl7TermMaintInfra"</system>> <code value="consumer"></code> </use> <value value="Højde"></value> </designation>

Determining the proper code, system and unit for Quantity

Given an observation code and corresponding system from the ValueSet "http://ehealth.sundhed.dk/vs/observation-codes" (see https://docs.ehealth.sundhed.dk/latest-released/ig/ValueSet-ehealth-observation-codes.html), how does one then determine how to specify an observed quantity or reference range? The following describes how to obtain values to set in Quantity.code, .system and .unit.

To get values forQuantity.code and Quantity.system use the ConceptMap "http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-ucum" (See https://docs.ehealth.sundhed.dk/latest-released/ig/ConceptMap-conceptmap-obs-code-to-ucum.html) as follows:

  1. Call $translate on the given code and system:

    1. GET <base-url>/fhir/ConceptMap/$translate?system=<system>&code=<code>

  2. On match found, the values to use in Quantity.codeandQuantity.systemare the matching concept’s code and system, respectively, where the source ConceptMap is "http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-ucum" (see example response below):

Example request and response on $translate on "http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-ucum"

Request:

GET <base-url>/fhir/ConceptMap/$translate?system=urn:oid:1.2.208.176.2.1&code=NPU03804

Response:

{     "resourceType": "Parameters",     "parameter": [         {             "name": "result",             "valueBoolean": true         },         {             "name": "message",             "valueString": "Matches found!"         },         {             "name": "match",             "part": [                 {                     "name": "equivalence",                     "valueCode": "specializes"                 },                 {                     "name": "concept",                     "valueCoding": {                         "system": "http://unitsofmeasure.org",                         "code": "kg",                         "display": "kilogram"                     }                 },                 {                     "name": "source",                     "valueUri": "http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-ucum"                 }             ]         }     ] }

 

To get the corresponding and printable value for Quantity.unit, use the ConceptMap "http://ehealth.sundhed.dk/ConceptMap/conceptmap-ucum-to-printsymbol" (see https://docs.ehealth.sundhed.dk/latest-released/ig/ConceptMap-conceptmap-ucum-to-printsymbol.html) as follows:

  1. Call $translate on the given system and code determined in the response above:

    1. GET <base-url>/fhir/ConceptMap/$translate?target=http://ehealth.sundhed.dk/vs/ehealth-ucum-printsymbol-supplement&code=<code>&system=<system>

  2. On match found, extract the matching concept (see example response below).

  3. Call $lookupon the matching (CodeSystem) system and code:

    1. GET <base-url>/fhir/CodeSystem/$lookup?system=http://ehealth.sundhed.dk/cs/ehealth-ucum-printsymbol-supplement&code=<code>

  4. On match found, the value to use in Quantity.unitis the matching concept’s designation.valuewhere the designation.language=da(see example response below). If there is no such designation, the printable value in Quantity.unit shall be left empty.

The $lookup does not return designation on eHealth Infrastructure Release 4 and other releases before Release 5.

Example request and response on $translate on "http://ehealth.sundhed.dk/ConceptMap/conceptmap-ucum-to-printsymbol"

Request (Note that URL-encoding of percent as code is used):

GET <base-url>/fhir/ConceptMap/$translate?target=http://ehealth.sundhed.dk/vs/ehealth-ucum-printsymbol-supplement&code=%25&system=http://unitsofmeasure.org

Response:

{     "resourceType": "Parameters",     "parameter": [         {             "name": "result",             "valueBoolean": true         },         {             "name": "message",             "valueString": "Matches found!"         },         {             "name": "match",             "part": [                 {                     "name": "equivalence",                     "valueCode": "specializes"                 },                 {                     "name": "concept",                     "valueCoding": {                         "system": "http://ehealth.sundhed.dk/cs/ehealth-ucum-printsymbol-supplement",                         "code": "%",                         "display": "percent"                     }                 },                 {                     "name": "source",                     "valueUri": "http://ehealth.sundhed.dk/ConceptMap/conceptmap-ucum-to-printsymbol"                 }             ]         }     ] }

Example request and response on $lookup on "http://ehealth.sundhed.dk/cs/ehealth-ucum-printsymbol-supplement" (see https://docs.ehealth.sundhed.dk/latest-released/ig/CodeSystem-ehealth-ucum-printsymbol-supplement.html)

Request (Note that URL-encoding of percent as code is used):

GET <base-url>/fhir/CodeSystem/$lookup?system=http://ehealth.sundhed.dk/cs/ehealth-ucum-printsymbol-supplement&code=%25

Response:

{     "resourceType": "Parameters",     "parameter": [         {             "name": "name",             "valueString": "UCUMPrintSymbolSupplement"         },         {             "name": "version",             "valueString": "0.6.0"         },         {             "name": "display",             "valueString": "percent"         },         {             "name": "abstract",             "valueBoolean": false         },         {             "name": "designation",             "part": [                 {                     "name": "language",                     "valueCode": "da"                 },                 {                     "name": "use"                 },                 {                     "name": "value",                     "valueString": "%"                 }             ]         }     ] }

 

Determining whether to provide measurement as integer or decimal

Given an observation codeand corresponding system from the ValueSet "http://ehealth.sundhed.dk/vs/observation-codes" (see https://docs.ehealth.sundhed.dk/latest-released/ig/ValueSet-ehealth-observation-codes.html), how does one determine whether an observed quantity or reference range shall be stated as an integer or decimal? While a particular device might produce a decimal with a given precision for a measure, it is up to the client/solution to convert to the form expected by the infrastructure. Whether integer or decimal, the value is set inQuantity.value.

To determine whether to use integer or decimal, use the ConceptMap "http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-value-type" (see https://docs.ehealth.sundhed.dk/latest-released/ig/ConceptMap-conceptmap-obs-code-to-value-type.html) as follows:

  1. Call $translate on the given code and system:

    1. GET <base-url>/fhir/ConceptMap/$translate?system=<system>&code=<code>&target=http://hl7.org/fhir/ValueSet/data-types

  2. On match found, indication of whether to use integer or decimal is the matching concept’s code and system, respectively, where the source ConceptMap is "http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-value-type" (see example response below).

  3. The codes integer and decimal in system http://hl7.org/fhir/data-types signify that the observed value or reference range shall be given as integer and decimal, respectively.

Example request and response on $translate on "http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-value-type"

Request:

GET <base-url>/fhir/ConceptMap/$translate?system=urn:oid:1.2.208.176.2.1&code=NPU03804&target=http://hl7.org/fhir/ValueSet/data-types

Response:

{     "resourceType": "Parameters",     "parameter": [         {             "name": "result",             "valueBoolean": true         },         {             "name": "message",             "valueString": "Matches found!"         },         {             "name": "match",             "part": [                 {                     "name": "equivalence",                     "valueCode": "specializes"                 },                 {                     "name": "concept",                     "valueCoding": {                         "system": "http://hl7.org/fhir/data-types",                         "code": "decimal",                         "display": "decimal"                     }                 },                 {                     "name": "source",                     "valueUri": "http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-value-type"                 }             ]         }     ] }

Correctly defining new terminology resources

If the need arise for new CodeSystems, ValueSets, SearchParams etc. to be added to the Terminology service, it’s important that their definitions adhere to the expectations of the IG Publisher, with regards to the URL. The IG publisher expects the filename, id and url to be aligned:

  1. File Name: The file name should reflect the id of the resource, typically prefixed with the resource type (e.g. CodeSystem-[id].json)

  2. ID: It must be a simple alphanumeric string (with optional dashes or underscores) and should match the file name (excluding the resource type prefix).

  3. URL: This is the canonical URL of the resource, it must include the id as the last segment, and should match the structure derived from the id and filename.