On this page:

5.8Terminology

 

Smile CDR has a number of features related to the use and management of coded values. Before beginning with these, you may want to start by reading about Using Codes in Resources.

5.8.1Uploading CodeSystems

 

Smile CDR ships with internal support for all CodeSystems that are distributed as a part of the FHIR release itself. For example, the Administrative Gender CodeSystem is preloaded into Smile CDR and can be interacted with using standard terminology operations such as $lookup.

In many cases, it is useful to upload your own CodeSystems for use in validation and search operations. This might mean uploading standard vocabularies such as LOINC or loading custom vocabularies such as local CodeSystems defined for organizational use.

When uploading a CodeSystem, there are two content modes that can be used. The content mode is specified in the CodeSystem.content element:

  • complete – means that all possible codes are explicitly defined within the CodeSystem. See codesystem-complete-example.json for an example of a complete CodeSystem.
  • external – means that codes are not explicitly included inside the CodeSystem resource, and are instead loaded through other operations. Large CodeSystems such as LOINC and SNOMED CT benefit from this mode because they have so many codes that it would not be realistic to represent them all in a single FHIR resource body.

5.8.2Uploading External CodeSystems

 
Uploading external terminologies requires the FHIR_UPLOAD_EXTERNAL_TERMINOLOGY permission.

Smile CDR has the ability to import several standard terminology code systems using their native distribution formats. It is also possible to upload external terminology containing custom or locally defined codes. This is done using the $upload-external-code-system operation, and can be automated using the Smile CLI Tool (smileutil) command.

The following table lists the Standard CodeSystems supported by Smile CDR, as well as their URL and required input format.

CodeSystem URL File Format
LOINC http://loinc.org LOINC Complete Download ZIP
SNOMED CT http://snomed.info/sct RF2 Distribution in ZIP
All Others Any Any CodeSystem may be uploaded using the CSV Vocabulary Input Files format described below.

5.8.3Uploading LOINC

 

Smile CDR has the ability to ingest and process the distribution format for the LOINC vocabulary. LOINC is a rich set of codes related to health measurements, observations, and documents. LOINC is most commonly known for its rich set of codes to describe laboratory testing orders and results.

In order to upload LOINC, the LOINC and RELMA Complete Download File download should be selected from the LOINC website. This file will have a filename similar to Loinc_N.NN.zip. It is available from the LOINC Downloads page.

Input Files

The following input files are supported (note that version numbers given are only examples; newer and older versions of these files may also be supported).

Filename Required? Description
loincupload.properties This optional file is not a part of the LOINC distribution and must be created manually. It contains version information about the upload.
LOINC_2.66.zip Yes LOINC Distribution

The loincupload.properties File

If present, this file should contain contents similar to the following:

# This is the version identifier for the AnswerList file
answerlist.version=Beta.1
# This is the version identifier for uploaded ConceptMap resources
conceptmap.version=Beta.1

Performing the Upload

The Smile CLI Tool (smileutil) Upload Terminology command can be used to upload LOINC files.

The easiest way to use this tool is to use the provided script in the terminology/loinc directory within the Smile CDR distribution.

With that in place, the upload-loinc.sh script can be used to invoke the appropriate command to upload these files.

5.8.4Uploading SNOMED CT

 

Smile CDR has the ability to ingest and process the distribution format for the SNOMED CT vocabulary. SNOMED CT is a very large and complex set of vocabulary covering almost all areas of healthcare.

Input Files

The following input files are supported (note that version numbers given are only examples; newer and older versions of these files may also be supported).

Filename Description
SnomedCT_RF2Release_INT_20160731.zip This file contains a complete release of SNOMED CT in the "RF2" format. The filename shown here is the international release of SNOMED CT, but national editions may be used instead as they share the same release format.

5.8.5Uploading Custom Vocabularies

 

If you have a set of concepts that is not already supported by one of the formats above, you can convert it into a standard HAPI FHIR custom vocabulary format and then upload it.

This approach uses one or more CSV files that are required to be in a specific format; therefore converting your content to this format (or authoring it natively in this format) is a prerequisite.

Performing the Upload

In order to upload custom terminology using the standard HAPI FHIR import format, the file(s) described above should be packaged into a ZIP file.

The Smile CLI Tool (smileutil) Upload Terminology command can be then be used to upload this file. An example command is shown below:

bin/smileutil upload-terminology -d myfiles.zip -v r4 -t "http://localhost:8000" -u "http://example.com/labCodes"

5.8.6Applying Deltas to External CodeSystems

 

A pair of FHIR operations can be used to add or remove codes from external CodeSystems. These operations directly add or remove the codes from the tables that are used for live processing without triggering a new version of the related CodeSystem resource. As such they are useful for maintaining terminology that is being used in a live environment.

5.8.7Delta Add Operation: $apply-codesystem-delta-add

 

The $apply-codesystem-delta-add operation can be used to add concepts to an existing external Codeystem. This operation takes the following parameters:

Name Cardinality Type Description
system 1..1 uri Specifies the CodeSystem URL to apply the delta to.
file 1..* Attachment Specifies the files that are to be uploaded. Files may be included in the attachment as raw CSV/JSON/XML files, or may also be combined into a compressed ZIP file which is included in the attachment instead.

Example

The following example shows an invocation of the Delta Add operation. This payload should be a POST to the following URL: http://serverbase/CodeSystem/$apply-codesystem-delta-add

The payload is shown below. Note that the following fields must be populated in the file Attachment elements:

  • contentType: Specifies the payload type (should be text/csv, application/zip, or a FHIR Mimeype).
  • data: Contains the raw Base64 encoded payload.
  • url: Used by the upload processor to determine the type of file being uploaded (e.g. concepts.csv vs hierarchy.csv). See CSV Vocabulary Input Files below for descriptions of the files to upload.
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "system",
      "valueUri": "http://example.com/cs"
    },
    {
      "name": "file",
      "valueAttachment": {
        "contentType": "text/csv",
        "data": "Q09ERSxESVNQTEFZCgpDSEVNLENoZW1pc3RyeQpIQixIZW1vZ2xvYmluCk5FVVQsTmV1dHJvcGhpbHMKCk1JQ1JPLE1pY3JvYmlvbG9neQpDJlMsQ3VsdHVyZSBhbmQgU2Vuc2l0aXZpdHkK",
        "url": "file:/concepts.csv"
      }
    },
    {
      "name": "file",
      "valueAttachment": {
        "contentType": "text/csv",
        "data": "UEFSRU5ULENISUxECgpDSEVNLEhCCkNIRU0sTkVVVAoKTUlDUk8sQyZTCg==",
        "url": "file:/hierarchy.csv"
      }
    }
  ]
}

5.8.8Delta Remove Operation: $apply-codesystem-delta-remove

 

The $apply-codesystem-delta-remove operation can be used to remove concepts from an existing external Codeystem. This operation takes the following parameters:

Name Cardinality Type Description
system 1..1 uri Specifies the CodeSystem URL to apply the delta to.
file 1..* Attachment Specifies the files that are to be uploaded. Files may be included in the attachment as raw CSV/JSON/XML files, or may also be combined into a compressed ZIP file which is included in the attachment instead.

Example

The following example shows an invocation of the Delta Remove operation. This payload should be a POST to the following URL: http://serverbase/CodeSystem/$apply-codesystem-delta-remove

The payload is shown below:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "value",
      "resource": {
        "resourceType": "CodeSystem",
        "url": "http://example.com/labCodes",
        "concept": [
          {
            "code": "HB"
          },
          {
            "code": "NEUT"
          }
        ]
      }
    }
  ]
}

5.8.9Reference: CSV Vocabulary Input Files

 

A zip file should be created that has the following file(s) listed below as contents. Note that all CSV files are required to have a header line containing the column names as the first line. This is shown in the examples below.

Concepts File: concepts.csv

This file should have the following columns:

  • CODE – contains the concept code
  • DISPLAY – contains the concept display name

Example:

CODE,DISPLAY

CHEM,Chemistry
HB,Hemoglobin
NEUT,Neutrophils
MICRO,Microbiology
C&S,Culture and Sensitivity

Hierarchy File: hierarchy.csv

This file contains optional hierarchy information if your codes have a parent-child hierarchy. This file should have the following columns:

  • PARENT – contains the concept code for the parent
  • CHILD – contains the concept code for the child

Example:

In the example below, the HB and NEUT concept will be children of the CHEM concept. The C&S concept will be a child of the MICRO concept.

PARENT,CHILD

CHEM,HB
CHEM,NEUT
MICRO,C&S

Omitting hierarchy.csv

The hierarchy.csv file is always optional; if it is missing, all codes defined in concepts.csv are treated as root concepts (concepts with no parents).

Adding Child Records

When using this file for the Delta Add Operation is is possible to specify PARENT codes that do not exist in concepts.csv but are already present in the existing CodeSystem. In this case, the child code is added as a child to the existing PARENT code, whether it is a root concept itself, or is a child as well.

CodeSystem Definition: codesystem.json or codesystem.xml

This file contains the CodeSystem definition. If this file is not supplied and a CodeSystem resource already exists for the given CodeSystem URL, the existing CodeSystem resource is not modified. If no resource already exists, a simple CodeSystem resource is automatically generated.

Example:

{
	"resourceType": "CodeSystem",
	"url": "http://example.com/labCodes",
	"name": "Example Lab Codes",
	"description": "A set of lab codes",
	"status": "active",
	"publisher": "Example Organization Corporation Worldwide",
	"date": "2019-07-30",
	"content": "not-present"
}