Sharing Valuesets, Codes, and Maps (SVCM)
1.5.1 - Trial-Implementation International flag

This page is part of the Sharing Valuesets, Codes, and Maps (SVCM) (v1.5.1: Publication) based on FHIR R4. This is the current published version. For a full list of available versions, see the Directory of published versions

2:3.98 Lookup Code [ITI-98]

This section corresponds to transaction [ITI-98] of the IHE IT Infrastructure Technical Framework. Transaction [ITI-98] is used by the Terminology Consumer and Terminology Repository Actors.

2:3.98.1 Scope

This transaction is used by the Terminology Consumer to lookup a given code to return the full details. The request is received by the Terminology Repository. The Terminology Repository processes the request and returns a response of the code details as a Parameters Resource.

2:3.98.2 Actor Roles

Table 2:3.98.2-1: Actor Roles

Actor: Terminology Consumer
Role: Requests code details from the Terminology Repository.
Actor: Terminology Repository
Role: Returns information for the code based on criteria provided by the Terminology Consumer.

2:3.98.3 Referenced Standards

2:3.98.4 Messages

Terminology ConsumerTerminology RepositoryLookup Code Request:HTTP GET <Base>/CodeSystem/$lookupLookup Code Response:Parameters

Figure 2:3.98.4-1: Interaction Diagram

2:3.98.4.1 Lookup Code Request Message

The Lookup Code Request message is a FHIR $lookup operation on the CodeSystem Resource.

2:3.98.4.1.1 Trigger Events

A Terminology Consumer triggers a Lookup Code Request to a Terminology Repository according to the business rules for the lookup. These business rules are outside the scope of this transaction.

2:3.98.4.1.2 Message Semantics

A Terminology Consumer initiates an $lookup request using HTTP GET as defined at http://hl7.org/fhir/codesystem-operation-lookup.html on the CodeSystem Resource. The required input parameters are identified in Table 2:3.98.4.1.2-1.

The URL for this operation is: [base]/CodeSystem/$lookup?[parameter=value]

Where [base] is the URL of Terminology Repository.

See ITI TF-2: Appendix W for informative implementation material for this transaction.

Table 2:3.98.4.1.2-1: Lookup Code Message HTTP Input Parameters

Input Parameter Name IHE Constraint Search Type Description
code
[0..1]
[1..1] code The code that is to be located. If a code is provided, a system must be provided.
system
[0..1]
[1..1] uri The system for the code that is to be located.
_format
[0..1]
mime-type The requested format of the response from the mime-type value set. See ITI TF-2: Appendix Z.6.
version
[0..1]
string The version of the system, if one was provided in the source data.
coding
[0..1]
[0..0]
This parameter is not allowed when the code+system parameters are used.
Coding
date
[0..1]
dateTime The date for which the information should be returned. Normally, this is the current conditions (which is the default value) but under some circumstances, systems need to access this information as it would have been in the past. A typical example of this would be where code selection is constrained to the set of codes that were available when the patient was treated, not when the record is being edited. Note that which date is appropriate is a matter for implementation policy.
displayLanguage
[0..1]
code The requested language for display (see $expand.displayLanguage).
property
[0..*]
code A property that the client wishes to be returned in the output. If no properties are specified, the server chooses what to return. The following properties are defined for all code systems: url, name, version (code system info) and code information: display, definition, designation, parent and child, and for designations, lang.X where X is a designation language code. Some of the properties are returned explicit in named parameters (when the names match), and the rest (except for lang.X) in the property parameter group.
2:3.98.4.1.2.1 Example Request Message

An example request message from http://hl7.org/fhir/codesystem-operation-lookup.html is:

GET [base]/CodeSystem/$lookup?system=http://loinc.org&code=1963-8
2:3.98.4.1.3 Expected Actions

The Terminology Repository shall process the input parameters to discover the code that matches the parameters given and return a response as per Section 2:3.98.4.2 or an OperationOutcome Resource with an error message.

2:3.98.4.2 Lookup Code Response Message

2:3.98.4.2.1 Trigger Events

The Terminology Repository found the code matching the input parameters specified by the Terminology Consumer as a result of a Lookup Code Request.

2:3.98.4.2.2 Message Semantics

See ITI TF-2: Appendix Z.6 for more details on response format handling. See ITI TF-2: Appendix Z.7 for handling guidance for Access Denied.

The response message is a FHIR Parameters Resource with properties of the code based on the out parameters defined at http://hl7.org/fhir/codesystem-operation-lookup.html and reproduced in Table 2:3.98.4.2.2-1.

Table 2:3.98.4.2.2-1: Lookup Code Message HTTP Output Parameters

Parameter Name Type Description
name
[1..1]
string A display name for the code system
version
[0..1]
string The version that these details are based on
display
[1..1]
string The preferred display for this concept
designation
[0..*]
Additional representations for this concept
designation.language
[0..1]
code The language this designation is defined for
designation.use
[0..1]
Coding A code that details how this designation would be used
designation.value
[1..1]
string The text value for this designation
property
[0..*]
One or more properties that contain additional information about the code, including status. For complex terminologies (e.g., SNOMED CT, LOINC, medications), these properties serve to decompose the code
property.code
[1..1]
code Identifies the property returned
property.value
[0..1]
code | Coding | string | integer | boolean | dateTime | decimal The value of the property returned
property.description
[0..1]
string Human Readable representation of the property value (e.g., display for a code)
property.subproperty
[0..*]
Nested Properties (mainly used for SNOMED CT decomposition, for relationship Groups)
property.subproperty.code
[1..1]
code Identifies the sub-property returned
property.subproperty.value
[1..1]
code | Coding | string | integer | boolean | dateTime | decimal The value of the sub-property returned
property.subproperty.description
[0..1]
string Human Readable representation of the sub-property value (e.g., display for a code)
2:3.98.4.2.2.1 Example Response Message

An example successful response message from http://hl7.org/fhir/codesystem-operation-lookup.html is:

HTTP/1.1 200 OK
[other headers]

{
  "resourceType" : "Parameters",
  "parameter" : [
    {
      "name" : "name",
      "valueString" : "LOINC"
    },
    {
      "name" : "version",
      "valueString" : "2.48"
    },
    {
      "name" : "display",
      "valueString" : "Bicarbonate [Moles/volume] in Serum"
    },
    {
      "name" : "abstract",
      "valueString" : "false"
    },
    {
      "name" : "designation",
      "part" : [
        {
          "name" : "value",
          "valueString" : "Bicarbonate [Moles/volume] in Serum"
        }
      ]
    }
  ]
}

An example failed response message from http://hl7.org/fhir/codesystem-operation-lookup.html is:

HTTP/1.1 200 OK
[other headers]

{
  "resourceType": "OperationOutcome",
  "id": "exception",
  "text": {
    "status": "additional",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Code "ABC-23" not found</div>"
  },
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Code "ABC-23" not found"
      }
    }
  ]
}
2:3.98.4.2.3 Expected Actions

The Terminology Consumer has received the response and continues with its workflow.

2:3.98.5 Security Considerations

See the general Security Consideration in ITI TF-1: 51.5.

2:3.98.5.1 Security Audit Considerations

Note that the same audit message is recorded by both Terminology Consumer and Repository. The difference being the Audit Source element. Both sides record to show consistency between the message sent by the Consumer and the action taken at the Registry.

The actors involved shall record audit events according to the Audit Event for Lookup Code by the Terminology Consumer and Repository.