Current Build
Vocabulary Work GroupMaturity Level: 5 Trial UseCompartments: Not linked to any defined compartments

This resource has 3 operations associated with it:

$lookupConcept Look Up & Decomposition
$subsumesSubsumption Testing
$composeCode Composition based on supplied properties

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

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 structure terminology

The official URL for this operation definition is

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

Formal Definition (as a OperationDefinition).

URL: [base]/CodeSystem/$lookup

This is an idempotent operation

In Parameters:
NameCardinalityTypeBindingProfileDocumentation
code0..1code

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

system0..1uri

The system for the code that is to be located

version0..1string

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

coding0..1Coding

A coding to look up

date0..1dateTime

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.

displayLanguage0..1code

The requested language for display (see ExpansionProfile.displayLanguage)

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

Out Parameters:
NameCardinalityTypeBindingProfileDocumentation
name1..1string

A display name for the code system

version0..1string

The version that these details are based on

display1..1string

The preferred display for this concept

designation0..*

Additional representations for this concept

designation.language0..1code

The language this designation is defined for

designation.use0..1Coding

A code that details how this designation would be used

designation.value1..1string

The text value for this designation

property0..*

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.code1..1code

Identifies the property returned

property.value0..1code | Coding | string | integer | boolean | dateTime

The value of the property returned

property.description0..1string

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

property.subproperty0..*

Nested Properties (mainly used for SNOMED CT decomposition, for relationship Groups)

property.subproperty.code1..1code

Identifies the sub-property returned

property.subproperty.value1..1code | Coding | string | integer | boolean | dateTime

The value of the sub-property returned

property.subproperty.description0..1string

Human Readable representation of the 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.

Looking up a code/system (Request):

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

Lookup using a Coding (Request):

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:

HTTP/1.1 200 OK
[other headers]

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

 

Test the subsumption relationship between code/Coding A and code/Coding B given the semantics of subsumption in the underlying code system (see hierarchyMeaning)

The official URL for this operation definition is

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

Formal Definition (as a OperationDefinition).

URL: [base]/CodeSystem/$subsumes

URL: [base]/CodeSystem/[id]/$subsumes

This is an idempotent operation

In Parameters:
NameCardinalityTypeBindingProfileDocumentation
codeA0..1code

The "A" code that is to be tested. If a code is provided, a system must be provided

codeB0..1code

The "B" code that is to be tested. If a code is provided, a system must be provided

system0..1uri

The code system in which subsumption testing is to be performed. This must be provided unless the operation is invoked on a code system instance

version0..1string

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

codingA0..1Coding

The "A" Coding that is to be tested. The code system does not have to match the specified subsumption code system, but the relationships between the code systems must be well established

codingB0..1Coding

The "B" Coding that is to be tested. The code system does not have to match the specified subsumption code system, but the relationships between the code systems must be well established

Out Parameters:
NameCardinalityTypeBindingProfileDocumentation
outcome1..1code

The subsumption relationship between code/Coding "A" and code/Coding "B". There are 4 possible codes to be returned: equivalent, subsumes, subsumed-by, and not-subsumed. If the server is unable to determine the relationship between the codes/Codings, then it returns an error (i.e. an OperationOutcome)

Using simple parameters: is 'Viral hepatitis' (3738000) a 'Disorder of liver' (235856003)? (Request):

GET [base]/CodeSystem/$subsumes?system=http://snomed.info/sct&codeA=3738000&codeB=235856003

Using Codings (Request):

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

<Parameters xmlns="http://hl7.org/fhir">
  <!-- Subsumption testing - use SNOMED CT rules -->
  <parameter>
    <name value="system"/>
    <valuUri value="http://snomed.info/sct"/>
  </parameter>
  <!-- Australian distribution -->
  <parameter>
    <name value="version"/>
    <valuString value="http://snomed.info/sct/32506021000036107/version/20160430"/>
  </parameter>
  <parameter>
    <name value="codingA"/>
    <valueCoding>
      <system value="http://snomed.info/sct"/>
      <code value="3738000"/>
    </valueCoding>
  </parameter>
  <parameter>
    <name value="codingB"/>
    <valueCoding>
      <system value="http://snomed.info/sct"/>
      <code value="235856003"/>
    </valueCoding>
  </parameter>
</Parameters>

Response:

HTTP/1.1 200 OK
[other headers]

{
  "resourceType" : "Parameters",
  "parameter" : [
    {
    "name" : "outcome",
    "valueCode" : "subsumed-by"
  }
}

 

Given a set of properties, return one or more possible matching codes

This operation takes a set of properties, and examines the code system looking for codes in the code system that match a set of known properties.

When looking for matches, there are 3 possible types of match: * a complete match - a code that represents all the provided properties correctly * a partial match - a code that represents some of the provided properties correctly, and not others * a possible match - a code that may represent the provided properties closely, but may capture less or more precise informationfor some of the properties

The $compose operation can be called in one of 2 modes: * By a human, looking for the best match for a set of properties. In this mode, the server returns a list of complete, possible or partial matches (possibly with comments), so that the user can choose (or not) the most appropriate code * By a machine (typically in a system interface performing a transformation). In this mode, the server returns only a list of complete and partial matches, but no possible matches. The machine can choose a code from the list (or not) based on what properties are not coded

These modes are differentiated by the 'exact' parameter, so the client can indicate whether it only wants exact matches (including partial matches) or whether potential matches based on text matching are desired

The compose operation is still preliminary. The interface can be expected to change as more experience is gained from implementations.

The official URL for this operation definition is

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

Formal Definition (as a OperationDefinition).

URL: [base]/CodeSystem/$compose

URL: [base]/CodeSystem/[id]/$compose

This is an idempotent operation

In Parameters:
NameCardinalityTypeBindingProfileDocumentation
system0..1uri

The system in which composition is to be performed. This must be provided unless the operation is invoked on a code system instance

version0..1string

The version of the system for the inferencing to be performed

property0..*

One or more properties that contain information to be composed into the code

property.code1..1code

Identifies the property provided

property.value0..1code | Coding | string | integer | boolean | dateTime

The value of the property provided

property.subproperty0..*

Nested Properties (mainly used for SNOMED CT composition, for relationship Groups)

property.subproperty.code1..1code

Identifies the sub-property provided

property.subproperty.value1..1code | Coding | string | integer | boolean | dateTime

The value of the sub-property provided

exact1..1boolean

Whether the operation is being used by a human, or a machine. If the operation is being used by a human, the terminology server can return a list of possible matches, with commentary. For a machine, the server returns sure matches, or none at all

compositional0..1boolean

Post-coordinated expressions are allowed to be returned in the matching codes (mainly for SNOMED CT). Default = false

Out Parameters:
NameCardinalityTypeBindingProfileDocumentation
match0..*

Concepts returned by the server as a result of the inferencing operation

match.code1..1Coding

A code that matches the properties provided

match.unmatched0..*

One or more properties that contain properties that could not be matched into the code

match.unmatched.code1..1code

Identifies the property provided

match.unmatched.value1..1code | Coding | string | integer | boolean | dateTime

The value of the property provided

match.unmatched.property0..*

Nested Properties (mainly used for SNOMED CT composition, for relationship Groups)

match.unmatched.property.code1..1code

Identifies the sub-property provided

match.unmatched.property.value1..1code | Coding | string | integer | boolean | dateTime

The value of the sub-property provided

match.comment0..1string

Information about the quality of the match, if operation is for a human

Request:

<Parameters xmlns="http://hl7.org/fhir">
  <parameter>
    <name value="system"/>
    <valueUri value="http://snomed.info/sct"/>
  </parameter>
  <parameter>
    <name value="exact"/>
    <valueBoolean value="true"/>
  </parameter>
  <parameter>
    <name value="property"/>
    <part>
      <name value="code"/>
      <valueCode value="focus"/>
    </part>
    <part>
      <name value="value"/>
      <!-- Measurement finding -->
      <valueCode value="118245000"/>
    </part>
  </parameter>
  <parameter>
    <name value="property"/>
    <part>
      <name value="code"/>
      <!-- Interprets -->
      <valueCode value="363714003"/>
    </part>
    <part>
      <name value="value"/>
      <!-- Bilirubin -->
      <valueCode value="302787001"/>
    </part>
  </parameter>
</Parameters>

SNOMED Composition - provide 2 properties, and ask for a single code for the whole (Response):



HTTP/1.1 200 OK
[other headers]

<Parameters xmlns="http://hl7.org/fhir">
    <parameter>
        <name value="match" />
        <part>
            <name value="code" />
            <valueCoding>
                <system value="http://snomed.info/sct" />
                <code value="365786009" />
                <display value="Bilirubin level - finding" />
            </valueCoding>
        </part>
    </parameter>
</Parameters>