FHIR Release 3 (STU) R4 Ballot #2 (Mixed Normative/Trial use)

This page is part of the FHIR Specification (v3.0.2: STU 3). (v3.5.0: R4 Ballot #2). 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

4.7.15 4.8.1 Resource CodeSystem - Operations

Vocabulary Work Group Maturity Level : 5   Trial Use Normative Compartments : Not linked to any defined compartments

This resource has 3 4 operations associated with it:

Subsumption Testing Identifies the sub-property returned 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 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: Name Cardinality Type Binding Profile Identifies the sub-property provided property.subproperty.value 1..1 code | Coding | string | integer | boolean | dateTime The value of the sub-property provided exact 1..1 boolean
$lookup Concept Look Up & Decomposition $subsumes Normative
$compose $validate-code Code Composition based on supplied properties For more information about operations, including how they are invoked, see Operations . 4.7.15.1 Concept Look Up & Decomposition 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: Name 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 0..1 uri The system for the code that is to be located version 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 ExpansionProfile.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 Out Parameters: Name 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 System 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 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 Validation code Normative
property.subproperty.value 1..1 code | Coding | string | integer | boolean | dateTime The value of the sub-property returned property.subproperty.description 0..1 string $subsumes 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. 4.7.15.1.1 Examples 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 " } ] } ] }   4.7.15.2 Subsumption Testing 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: Name Cardinality Type Binding Profile Documentation codeA 0..1 code The "A" code that is to be tested. If a code is provided, a system must be provided codeB 0..1 code The "B" code that is to be tested. If a code is provided, a system must be provided system 0..1 uri 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 version 0..1 string The version of the code system, if one was provided in the source data codingA 0..1 Coding Normative
codingB 0..1 Coding $find-matches Documentation outcome 1..1 code The subsumption relationship between code/Coding "A" and code/Coding "B". There are 4 possible Finding 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) 4.7.15.2.1 Examples 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" } }   4.7.15.3 Code Composition based on supplied properties 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: Name Cardinality Type Binding Profile Documentation system 0..1 uri The system in which composition is to be performed. This must be provided unless the operation is invoked on a code system instance version 0..1 string The version of the system for the inferencing to be performed property 0..* One or more properties that contain information to be composed into the code property.code 1..1 code Identifies the property provided property.value 0..1 code | Coding | string | integer | boolean | dateTime The value of the property provided property.subproperty 0..* Nested Properties (mainly used for SNOMED CT composition, for relationship Groups) property.subproperty.code 1..1 code Trial Use

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 compositional 0..1 boolean Post-coordinated expressions are allowed to be returned in the matching codes (mainly for SNOMED CT). Default = false Out Parameters: Name Cardinality Type Binding Profile Documentation match 0..* Concepts returned by the server as a result of the inferencing operation match.code 1..1 Coding A code that matches the properties provided match.unmatched 0..* One or more properties that contain properties that could not be matched into the code match.unmatched.code 1..1 code Identifies the property provided match.unmatched.value 1..1 code | Coding | string | integer | boolean | dateTime The value of the property provided match.unmatched.property 0..* Nested Properties (mainly used for SNOMED CT composition, for relationship Groups) match.unmatched.property.code 1..1 code Identifies the sub-property provided match.unmatched.property.value 1..1 code | Coding | string | integer | boolean | dateTime The value of the sub-property provided match.comment 0..1 string Information information about the quality of the match, if operation is for a human 4.7.15.3.1 Examples 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>   operations, including how they are invoked, see Operations .