Release 5 4

This page is part of the FHIR Specification (v5.0.0: R5 (v4.0.1: R4 - Mixed Normative and STU ). This is the ) in it's permanent home (it will always be available at this URL). The current published version. 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

4.8.21.1 Operation $lookup on CodeSystem

Terminology Infrastructure Vocabulary Work Group   Maturity Level : N Normative (from v4.0.1) Compartments : N/A
This page has been approved as part of an ANSI standard. See the Conformance Package for further details.

Given a code/system, or a Coding, get additional details about the concept, including definition, status, designations, and properties. One of the products of this operation is a full decomposition of a code from a structured terminology.

When invoking this operation, a client SHALL provide both a system and a code, either using the system+code parameters, or in the coding parameter. Other parameters are optional.

The canonical official URL for this operation definition is 

http://hl7.org/fhir/OperationDefinition/CodeSystem-lookup

Formal Definition (as a OperationDefinition ).

URL: [base]/CodeSystem/$lookup

URL: [base]/CodeSystem/[id]/$lookup This is an idempotent operation

property.subproperty.source 0..1 canonical If information from a supplement is included as a subproperty (e.g. any additional subproperty or subproperty value), then this parameter must assert the url of the supplement.
In Parameters:
Name Scope Cardinality Type Binding Profile Documentation
code 0..1 code

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

system type 0..1 uri

The system for the code that is to be located

version type 0..1 string

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

coding 0..1 Coding

A coding to look up

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 acccess 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 CodeSystem.concept.designation.language) $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. These Some of the properties are returned explicitly explicit in named out parameters with matching names, or in designations. In addition, any property codes defined by this specification or by (when the CodeSystem ( CodeSystem.property.code ) are allowed, names match), and these are returned in the out parameter property useSupplement 0..* canonical Supplements to take into account when performing the $lookup operation. The supplements must be for the same CodeSystem. By default, supplements for the code system are not automatically included except where they provide additional designations that may be indicated by, rest (except for example, lang.X) in the displayLanguage property parameter group

Out Parameters:
Name Scope Cardinality Type Binding Profile Documentation
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

definition 0..1 string A statement of the meaning of the concept from the code system 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.additionalUse 0..* Coding Additional codes that detail how this designation would be used (if there is more than one) 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 | boolean string | code integer | boolean | dateTime | decimal | integer | string

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.source 0..1 canonical If information from a supplement is included as a property (e.g. any additional property or property value), then this parameter must assert the url of the supplement. 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 | boolean string | code integer | boolean | dateTime | decimal | integer | string

The value of the sub-property returned

property.subproperty.description 0..1 string

Human Readable representation of the sub-property property value (e.g. display for a code)

Note that the $lookup operation is more than just a code system search - the server finds the concept, and gathers the return information from the underlying code system definitions.

4.8.21.1.1 Examples

Request: #1 Looking up a code/system 

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

Response to request: #1 Request: Lookup using a Coding 


POST [base]/CodeSystem/$lookup
[other headers]

<Parameters xmlns="http://hl7.org/fhir">
  <parameter>
    <name value="coding"/>
  <valueCoding>
    <system value="http://loinc.org"/>
    <code value="1963-8"/>
  </valueCoding>
  </parameter>
</Parameters>

Response: When the request can be processed ok 


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

Request: #2 Lookup using a Coding POST [base]/CodeSystem/$lookup [other headers] <Parameters xmlns="http://hl7.org/fhir"> <parameter> <name value="coding"/> <valueCoding> <system value="http://acme.com/fhir/CodeSystem/"/> <code value="ABC-23"/> </valueCoding> </parameter> </Parameters> Response to request: #2 an Response: An error - when e.g. the requested code is not known 


HTTP/1.1 400 Bad Request
[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"
      }
    }
  ]
}

 

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