R4 Draft for Comment

This page is part of the FHIR Specification (v3.2.0: R4 Ballot 1). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

Vocabulary Work GroupMaturity Level: 3 Normative Compartments: Not linked to any defined compartments

Normative Candidate Note: This page is candidate normative content for R4 in the Conformance Package. Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.

This resource has 2 operations associated with it:

$translateConcept Translation
$closureClosure Table Maintenance

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

Translate a code from one value set to another, based on the existing value set and concept maps resources, and/or other additional knowledge available to the server.

One (and only one) of the in parameters (code, coding, codeableConcept) must 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, so implementers have to check the match.equivalence for each match

The official 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:
NameCardinalityTypeBindingProfileDocumentation
code0..1code

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

system0..1uri

The system for the code that is to be translated

version0..1string

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

source0..1uri

Identifies the value set used when the concept (system/code pair) was chosen. May be a logical id, or an absolute or relative location. 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

coding0..1Coding

A coding to translate

codeableConcept0..1CodeableConcept

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

target0..1uri

Identifies the value set in which a translation is sought. May be a logical id, or an absolute or relative location. If there's no target specified, the server should return all known translations, along with their source

targetsystem0..1uri

identifies a target code system in which a mapping is sought. This parameter is an alternative to the target 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

dependency0..*

Another element that may help produce the correct mapping

dependency.element0..1uri

The element for this dependency

dependency.concept0..1CodeableConcept

The value for this dependency

reverse0..1boolean

if this is true, then the operation should return all the codes that might be mapped to this code. This parameter reverses the meaning of the source and target parameters

Out Parameters:
NameCardinalityTypeBindingProfileDocumentation
result1..1boolean

True if the concept could be translated successfully. The value can only be true if at least one returned match has an equivalence which is not unmatched or disjoint

message0..1string

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)

match0..*

A concept in the target value set with an equivalence. Note that there may be multiple matches of equal or differing equivalence, and the matches may include equivalence values that mean that there is no match

match.equivalence0..1code

A code indicating the equivalence of the translation, using values from [ConceptMapEquivalence]{concept-map-equivalence.html}

match.concept0..1Coding

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.product0..*

Another element that is the product of this mapping

match.product.element0..1uri

The element for this product

match.product.concept0..1Coding

The value for this product

match.source0..1uri

The canonical URI for the concept map from which this mapping comes from

Request:

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

Response:

HTTP/1.1 200 OK
[other headers]

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "match",
      "part": [
        {
          "name": "equivalence",
          "valueCode": "equivalent"
        },
        {
          "name": "concept",
          "valueCoding": {
            "system": "http://hl7.org/fhir/v3/ActStatus",
            "code": "active",
            "userSelected": false
          }
        }
      ]
    }
  ]
}

 

This operation provides support for ongoing maintenance of a client-side transitive closure table based on server-side terminological logic. For details of how this is used, see Maintaining a Closure Table

The official URL for this operation definition is

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

Formal Definition (as a OperationDefinition).

URL: [base]/$closure

This is not an idempotent operation

In Parameters:
NameCardinalityTypeBindingProfileDocumentation
name1..1string

The name that defines the particular context for the subsumption based closure table

concept0..*Coding

Concepts to add to the closure table

version0..1id

A request to resynchronise - request to send all new entries since the nominated version was sent by the server

Out Parameters:
NameCardinalityTypeBindingProfileDocumentation
return1..1ConceptMap

A list of new entries (code / system --> code/system) that the client should add to its closure table. The only kind of entry mapping equivalences that can be returned are equal, specializes, subsumes and unmatched

Note: as this the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource

Request:

POST [base]/$closure

{
  "resourceType" : "Parameters",
  "parameter" : [
    {
      "name" : "name",
      "valueString" : "patient-problems"
    },
    {
      "name" : "concept",
      "valueCoding" : {
        "system" : "http://snomed.info/sct",
        "code" : "22298006",
      }
    }
  ]
}

Response:

HTTP/1.1 200 OK
[other headers]

{
  "resourceType": "ConceptMap",
  "identifier": "49088976-d54d-4d19-b868-3d4c18cebabb",
  "version": "8",
  "status": "active",
  "experimental": true,
  "date": "2012-06-13",
  "element": [
    {
      "codeSystem": "http://snomed.info/sct",
      "code": "22298006",
      "map": [
        {
          "codeSystem": "http://snomed.info/sct",
          "code": "128599005",
          "equivalence": "subsumes"
        }
      ]
    },
  ]
}