R6 Ballot (2nd Draft)

Publish-box (todo)

4.10.16.1 Operation $translate on ConceptMap

Terminology Infrastructure icon Work Group Maturity Level: 1Trial Use Compartments: N/A

Translate a code from one value set to another, based on the specified ConceptMap resource. If no ConceptMap resource is specified, then other additional knowledge available to the server may be used.

One (and only one) of the in parameters (sourceCode, sourceCoding, sourceCodeableConcept, targetCode, targetCoding, or targetCodeableConcept) SHALL be provided, to identify the code that is to be translated.

The operation returns a set of parameters including a 'result' for whether there is an acceptable match, and a list of possible matches. Note that the list of matches may include notes of codes for which mapping is specifically excluded (i.e. 'not-related-to'), so implementers have to check the target.relationship for each match. If a source* parameter is provided, the $translate operation will return all matches whereby the provided source concept is the source of a mapping relationship (in a specified ConceptMap or otherwise known to the server). If a target* parameter is provided, the $translate operation will return all matches whereby the provided target concept is the target of a mapping relationship (in a specified ConceptMap or otherwise known to the server). Note: The source value set is an optional parameter because in some cases, the client cannot know what the source value set is. However, without a source value set, the server may be unable to safely identify an applicable concept map, and would return an error. For this reason, a source value set SHOULD always be provided. Note that servers may be able to identify an appropriate concept map without a source value set if there is a full mapping for the entire code system in the concept map, or by manual intervention.

The canonical URL for this operation definition is

 http://hl7.org/fhir/OperationDefinition/ConceptMap-translate

Formal Definition (as a OperationDefinition).

URL: [base]/ConceptMap/$translate

URL: [base]/ConceptMap/[id]/$translate

This is an idempotent operation

In Parameters:
Name Scope Cardinality Type Binding Profile Documentation
url type 0..1 uri

A canonical URL for a concept map. The server must know the concept map (e.g. it is defined explicitly in the server's concept maps, or it is defined implicitly by some code system known to the server.

conceptMap type 0..1 ConceptMap

The concept map is provided directly as part of the request. Servers may choose not to accept concept maps in this fashion.

conceptMapVersion type 0..1 string

The identifier that is used to identify a specific version of the concept map to be used for the translation. This is an arbitrary value managed by the concept map author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available.

sourceCode 0..1 code

The code that is to be translated. If a code is provided, a system must be provided

system 0..1 uri

The system for the code that is to be translated

version 0..1 string

The version of the system, if one was provided in the source data

sourceScope 0..1 uri

Limits the scope of the $translate operation to source codes (ConceptMap.group.element.code) that are members of this value set.

sourceCoding 0..1 Coding

A coding to translate

sourceCodeableConcept 0..1 CodeableConcept

A full codeableConcept to validate. The server can translate any of the coding values (e.g. existing translations) as it chooses

targetCode 0..1 code

The target code that is to be translated to. If a code is provided, a system must be provided

targetCoding 0..1 Coding

A target coding to translate to

targetCodeableConcept 0..1 CodeableConcept

A full codeableConcept to validate. The server can translate any of the coding values (e.g. existing translations) as it chooses

targetScope 0..1 uri

Limits the scope of the $translate operation to target codes (ConceptMap.group.element.target.code) that are members of this value set.

targetSystem 0..1 uri

identifies a target code system in which a mapping is sought. This parameter is an alternative to the targetScope parameter - only one is required. Searching for any translation to a target code system irrespective of the context (e.g. target valueset) may lead to unsafe results, and it is at the discretion of the server to decide when to support this operation

dependency 0..*

Data from another attribute that may help produce the correct mapping

dependency.attribute 0..1 uri

The attribute for this dependency

dependency.value 0..1 code | Coding | string | boolean | Quantity

The data value for this dependency

Out Parameters:
Name Scope Cardinality Type Binding Profile Documentation
result 1..1 boolean

True if the concept could be translated successfully. The value can only be true if at least one returned match has a relationship other than 'not-related-to'.

message 0..1 string

Error details, for display to a human. If this is provided when result = true, the message carries hints and warnings (e.g. a note that the matches could be improved by providing additional detail)

match 0..*

A concept in the target value set with a relationship. Note that there may be multiple matches of equal or differing relationships, and the matches may include the 'not-related-to' relationship value which means that there is no translation

match.relationship 0..1 code

A code indicating the relationship (e.g., equivalent) of the translation, using values from ConceptMapRelationship

match.concept 0..1 Coding

The translation outcome. Note that this would never have userSelected = true, since the process of translations implies that the user is not selecting the code (and only the client could know differently)

match.property 0..*

A property of this mapping (may be used to supply for example, mapping priority, provenance, presentation hints, flag as experimental, and additional documentation)

match.property.uri 1..1 uri

The uri that identifies the property

match.property.value 1..1 Coding | string | integer | boolean | dateTime | decimal | code

The value of the property

match.product 0..*

A data value to go in an attribute that is the product of this mapping

match.product.attribute 1..1 uri

The attribute for this product

match.product.value 1..1 code | Coding | string | boolean | Quantity

The value for this product

match.dependsOn 0..*

An data value in an additional attribute that this mapping depends on

match.dependsOn.attribute 1..1 uri

The attribute for this product

match.dependsOn.value 1..1 code | Coding | string | integer | boolean | dateTime | decimal | uri | id

The value for this product

match.originMap 0..1 uri

The canonical reference to the concept map from which this mapping comes from

4.10.16.1.1 Examples

Request: Simple translate using specified ConceptMap

GET [base]/ConceptMap/$translate?url=http://hl7.org/fhir/ConceptMap/102
  &system=http://terminology.hl7.org/CodeSystem/v2-0487&code=ACNE

Request: General translate using any available map knowledge scoped by source and target ValueSets

GET [base]/ConceptMap/$translate?system=http://hl7.org/fhir/composition-status
  &code=preliminary&sourceScope=http://hl7.org/fhir/ValueSet/composition-status
  &targetScope=http://hl7.org/fhir/ValueSet/v3-ActStatus

Response: Successful translate with one match

HTTP/1.1 200 OK
[other headers]

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "result",
            "valueBoolean": true
        },
        {
            "name": "match",
            "part": [
                {
                    "name": "relationship",
                    "valueCode": "equivalent"
                },
                {
                    "name": "concept",
                    "valueCoding": {
                        "system": "http://snomed.info/sct",
                        "code": "309068002",
                        "display": "Skin lesion specimen"
                    }
                },
                {
                    "name": "originalMap",
                    "valueString": "http://hl7.org/fhir/ConceptMap/102"
                }
            ]
        }
    ]
}

Response: Successful translate with two matches, each indicating the source ConceptMap of the match

HTTP/1.1 200 OK
[other headers]

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "match",
      "part": [
        {
          "name": "relationship",
          "valueCode": "equivalent"
        },
        {
          "name": "concept",
          "valueCoding": {
            "system": "http://hl7.org/fhir/v3/ActStatus",
            "code": "active",
            "display": "active"
          }
        },
        {
          "name": "originalMap",
          "valueString": "http://hl7.org/fhir/ConceptMap/cm-composition-status-v3"
        }
      ]
    },
    {
      "name": "match",
      "part": [
        {
          "name": "relationship",
          "valueCode": "equivalent"
        },
        {
          "name": "concept",
          "valueCoding": {
            "system": "http://hl7.org/fhir/resource-status",
            "code": "draft",
            "display": "draft"
          }
        },
        {
          "name": "source",
          "valueString": "http://hl7.org/fhir/ConceptMap/sc-composition-status"
        }
      ]
    }
  ]
}

 

For more information about operations, including how they are invoked, see Operations.