Expanding Hierarchical CodeSystems and ValueSets

Many CodeSystem resources define concepts in a hierarchy, ex: parent code and child codes.

The hierarchy in a CodeSystem often indicates an "is-a" relationship between the parent code and the child codes. This is not always the case; the hierarchy can imply different kinds of relationships depending on the specific system.

ValueSets can be used to retrieve all of the codes that are a child of a specific code in a CodeSystem.

For example, suppose you have the following CodeSystem and there are 3 codes at the root level (P , Q and R) and each of these codes have children, some of which have further children.

{
  "resourceType": "CodeSystem",
  "url": "http://example.com/my_custom_codeSystem",
  "content": "complete",
  "concept": [ {
    "code": "P",
    "display": "Code P",
    "concept": [ {
      "code": "PP",
      "display": "Code PP",
      "concept": [ {
        "code": "PPP",
        "display": "Code PPP"
      } ]
    }, {
      "code": "PQ",
      "display": "Code PQ"
    } ]
  }, {
    "code": "Q",
    "display": "Code Q",
    "concept": [ {
      "code": "QP",
      "display": "Code QP"
    }, {
      "code": "QQ",
      "display": "Code QQ"
    } ]
  } , {
    "code": "R",
    "display": "Code R",
    "concept": [ {
      "code": "RP",
      "display": "Code RP"
    }, {
      "code": "RQ",
      "display": "Code RQ"
    } , {
      "code": "RR",
      "display": "Code RR"
    }]
  } ]
}

The hierarchy for the codes above can be visualized as follows:

|-- P
|   |-- PP
|   |   \-- PPP 
|   \-- PQ
\-- Q 
|   |-- QP
|   \-- QQ
\-- R 
    |-- RP
    \-- RQ
    \-- RR

To create a ValueSet containing all of the children of a specific code in this CodeSystem, a ValueSet with a filter can be defined:

{
   "resourceType": "ValueSet",
   "url": "http://example.com/my_custom_value_set",
   "status": "active",
   "compose": {
      "include": [ {
         "system": "http://example.com/my_custom_codeSystem",
         "filter": [ {
            "property": "concept",
            "op": "is-a",
            "value": "P"
         } ]
      } ]
   }
}

Note:

Note that the "is-a" filter will exclude the concept itself.

The following example combines an "is-a" filter with a simple explicit code inclusion in order to include the code "P" as well as all of its descendants.

{
   "resourceType": "ValueSet",
   "url": "http://example.com/my_custom_value_set",
   "status": "active",
   "compose": {
      "include": [ {
         "system": "http://example.com/my_custom_codeSystem",
         "filter": [ {
            "property": "concept",
            "op": "is-a",
            "value": "P"
         } ]
      }, {
         "system": "http://example.com/my_custom_codeSystem",
         "concept": [ {
           "code": "P"
         } ]
      } ]
   }
}