SMART TS, published by WHO. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/WorldHealthOrganization/smart-ts/tree/main and changes regularly. See the Directory of published versions

DAK DD Authoring Guide

Conceptual Model for SMART Guidelines Terminology Management using OCL

For high level information about what approach will be taken for terminology management for SMART Guidelines, see slides 1-16 of this deck

Setup and Prerequisites

1. An official OCL Organization should be created as the home for all WHO DAK content. In this example, it will be WHO-SG-Example.
2. Developers of the DAK dictionary will have an OCL account in the appropriate OCL instance, and they have been added to the WHO organization as a member.

Start up the DAK dictionary

​Visual demonstration for creating a DAK Data Dictionary as an OCL Source

1. Fill out required fields for this source, based on the DAK being developed. See "Dictionary Checklist –> DAK Dictionary (Source)" section below for details on what information to populate.

• Recommendation: While it is not required, using the OpenMRS Validation Schema may optionally be used in OCL to improve implementation of DAKs in OpenMRS instances. External IDs in the "ID Auto-Assignment" section should all be set to "UUID" to give all concepts and names/descriptions a unique identifier.
• Note: Sources will use the Purpose attribute as a way to tie DAK contents together, until resource packaging is more explicitly supported in OCL.

1. It is recommended that preliminary descriptive information about the DAK is provided in the Source About page, if available. This is the place to describe in detail the intended use of the DAK, assumptions, and other important information about its contents. It is also an ideal place to link to the other artifacts, GitHub reposotories, etc. that are related to your DAK. This content can be added at any time but should be populated before releasing a version of the DAK in order to appear in your FHIR terminology resource(s).
2. Click "Create Source" to submit information and create the DAK source. Once the page refreshes, ensure that the Canonical URL of the source is visible and correct. Click on the Source to enter it and to view its contents.

Creating Concepts in the DAK

Whether the data dictionary element represents a question, an answer, or something else, they all will be defined as concepts within the DAK source. We can give them different attributes to differentiate, and we can also add or manage mappings on concepts. These concepts can later be organized, enriched, or otherwise altered in the future, but we will focus on the initial creation of the concepts first.

Note that concepts should ideally be reused where possible, rather than created from scratch.

Searching for and reusing concepts

Use the search bar at the top of the page to input keywords or other search terms that could help to find an existing concept that meets the need of the DAK dictionary that is being developed.

Using the search results provided, look for a concept that is similar to the requirement for the DAK dictionary. This includes a similar display name, description, Attributes, and Associations. Note that, particularly for question concepts, having some imperfect matching in the associations section can be acceptable since the mappings can be changed later.

If multiple concepts appear in search results that meet the requirement, authors should use the following prioritization of terminology sources:

1. (If published) SMART Common Dictionary: Any concept can be reused verbatim or adapted (Note that any concepts from other DAK dictionaries should have a representation here, so no other DAK dictionaries should be required for searching unless they are in a pre-publication stage)
2. Other published DAKs

In general, it is better to reuse a concept as long as the intended meaning of the concept matches the requirement. Consult the relevant DAK authority for questions of similarity and appropriateness of reuse.

$clone

OCL's cloning operation can recreate a concept and its mappings, making it easier to reuse (and possibly adapt) in the current DAK dictionary. When selecting one or more concepts in OCL, use the Clone to Source button to bring up a prompt that will enable you to preview and customize this operation to make copies of a concepts for your own dictionary.

Note that the clone operation by default will "cascade", meaning it will recreate both the concept and its mappings if those mappings are of a certain type. This operation can be customized to change how this cascade works.

​Visual example of searching and cloning

Making adaptations to a cloned concept

Various adaptations can be made to concepts:

• Add new names/synonyms/descriptions, change the preferred name for the locale, etc.
• Change mappings or associations
• Change Attributes

Use OCL's Edit Concept button in the Actions menu to make these changes. If mapping changes are made, they will need to be confirmed with a terminologist before publication of L2/L3 artifacts (which will check for appropriate linkages, correct map types, etc.).

Adding translations to this concept can also be done using this action by creating new names and assigning a different Locale code to them.

Note that IDs cannot be changed on any concept.

​Visual example in OCL for editing a concept

Creating a Concept (e.g. a Data Element)

Click the "+" icon to "Add Concept". This will open the form to create a concept, which will contain the necessary fields to fill out for each data element.

​Visual demonstration for adding a concept in OCL

Click the "Create" button to submit the concept to OCL. OCL may return errors if improper values are provided.

​Here is a visual example of populating the attributes for an OCL concept, using an example from the DAK Dictionary Template.

See the Dictionary Checklist section for the required and optional attributes for concepts.

Adding Mappings to a Concept

Any concept can have mappings, including the following:

• Internal mappings: Connect two concepts in the DAK dictionary
• External mappings: Link a DAK dictionary concept to an external vocabulary, such as ICD-10

OCL's Associations section within a concept's details page allows you to add a mapping from that concept to another concept. In general, it is better to already know what concept you want to map to, since this Add Mapping form is not ideal for searching for a concept. This may require opening up another OCL tab to search for concepts, or you may need to search for codes in another terminology's browser e.g. the ICD-10 Browser.

Once you know your concept that you want to map to, navigate to the concept's Associations section and use the "Add new mapping" option or the Three-dot menu of another mapping to open a form that will help you to create the new association between data element and input option(s). Select the applicable Map Type, then select the source (i.e. the dictionary or reference vocabulary) that will contain the concept to map to. If that source does not exist in OCL, contact the OCL administrator.

Then you can input the code or name of the concept to map to. If OCL does not recognize that code or name in the source, it will allow you to provide your own name to the concept. This ensures that you can still provide meaningful mappings to a concept that OCL does not recognize.

See below for visual examples of adding mappings to a concept.

This process should be used not only to map concept to reference vocabs, but also back to the SMART Common Dictionary that will contain common concepts. If you cloned a concept from the SMART Common Dictionary, however, then this step has likely already been done by OCL for you.

​Visual demonstration for adding a mapping to a concept that OCL recognizes

​Visual demonstration for adding a mapping to a concept that OCL does not recognize

Creating input options for a coded data element

In the case that a new input option is needed for a coded data element (e.g. a new possible answer to a question concept), you first must create the concept in the DAK source, following the directions above. Searching for and reusing existing concepts is still preferable, but creating a new concept to serve as an input option will likely be needed at some point in the DAK development process.

Once all required input options for a coded data element have been created in the DAK source, open the details for the data element and navigate to the Associations section. Use the "Add new mapping" option or the Three-dot menu of another mapping to open a form that will help you to create the new association between data element and input option(s).

Map type options to be used in DAKs will be found in a WHO-managed repository in OCL. Consult with the appropriate DAK authority for details.

​Visual demonstration for adding a code as an input option to a data element

Working with Value Sets

Creating a value set from a data element's input options

Note: OCL collections are the repository type which contain other concepts, also known as a value set in FHIR terms.

1. Select the concepts to be added to the value set and click "Add to Collection"
   1. Create the value set (if not already existing) - Note that not all details need to be filled in now, but the Value Set's ID cannot be changed later.
2. A dialogue window will appear, which determines how much information should come into the collection with the selected concepts. In general, it is recommended to at least use the "Yes, include associated Mappings from the same source" cascade option.
3. Navigate to the newly added concepts in the value set to ensure that the appropriate concepts (and their mappings) were added into the value set correctly
4. Recommended - link the value set back to the data element concept using the "Value Set URL" (and "Value Set Canonical") attribute(s) (URL = OCL-specific URL, Canonical = Universal identifying URL)

​Visual demonstration for creating a value set (also known as a Collection) in OCL

Adapting an existing value set

Intensional value set adaptation

When an existing value set meets most of the requirements, but has slightly different values in the set for the DAK in development, the existing value set can be adapted using intensional references. Simply put, this allows the DAK developer to bring in another value set's contents using one command, rather than selecting concepts one at a time. Once that new value set has been started, new concepts can be added using the instructions in the "Creating a value set from a data element's input options" section. Concepts can also be removed from the value set by selecting the concepts and clicking "Remove references".

When removing concepts or mappings from a collection, OCL will often ask if you want to "Remove reference(s)" or "Exclude concept(s)/mapping(s) from collection". Often, OCL's recommended option there should be used. Since an intensional reference can bring in multiple concepts and mappings with it, the most common recommended option is to "Exclude" the concept, allowing you to essentially "include all concepts from another value set EXCEPT for this particular concept". Many exclusions can be made if multiple concepts should not appear in the value set.

All references, including those that brought content into the value set (i.e. Include references) and those that kept content out of the value set (i.e. Exclude references), can be seen in the collection's References tab. This may help to explain why content is or is not appearing in the collection.

Note that there are known issues with this workflow, so it is important to check the value set contents. If this method fails, follow the instructions in the "Extensional value set adaptation" section.

In the next visual example, a new Danger Signs value set is created intensionally from the previous Danger Signs value set. Then, a concept is removed using an "Exclusion" reference.

​Visual example for intensional value set creation and code exclusion

Extensional value set adaptation

When intensional value set building is not appropriate or working as expected, then it is appropriate to create new value sets using the similar method described in the "Creating a value set from a data element's input options" section. Concepts in the existing value set can be selected, one at a time, and added into the new, adapted value set. From that new value set, new concepts can be added or removed by selecting the concepts and clicking "Remove references" as described in the "Intensional value set adaptation" section.

Managing versions

Save versions of all created repositories at the end of the development process when ready to share content for broader feedback. This can be done within the Version tab of all sources and collections (i.e. CodeSystems and ValueSets). Creating a version means that OCL will save your current progress in that repository.

Until a version is saved, all of your work done so far will live in the HEAD version of your repository. This is like a workspace, whereas the saved version is the more official "point in time" content set, which is frozen and cannot be edited. Implementers, e.g. systems who uptake the dictionary, should be directed towards specific repo versions in OCL, rather than the HEAD version.

Retrieving content in a FHIR format from an OCL repository is ONLY possible if a version has been saved.

Note that any version can be released or unreleased. This is a simple flag to let users know that the version is published and ready to go.

Guidance for Version numbers can be found in the SMART IG Starter Kit. Version numbers for DAK artifacts are independent, meaning that, for example, Data Dictionary versioning can be done independently of downstream L3 artifacts.

​Visual demonstration for creating a version of a repository within OCL

Importing an existing DAK spreadsheet

Python scripts or other tools to prepare the DAK dictionary for import into OCL may be also used to create terminology resources in OCL. However, this likely will not fully follow the DAK model in OCL and will still require additional enrichment, mappings to DAK concepts, etc. in OCL.

Bulk Import documentation for OCL is available to support users in creating dictionaries, value sets, concepts, mappings, etc. If spreadsheet-based DAK development is preferred, then bulk importing may be a viable option to create those resources in OCL, as long as the developer is comfortable with using existing tooling or with transforming the DAK spreadsheet into an OCL Bulk Import format (either CSV or JSON lines).

This method will often require some additional consultation from an OCL administrator or a SMART Guidelines community member.

Existing (albeit nascent and not fully tested and validated) tooling for this spreadsheet conversion also may be used, including the following:

• DAK spreadsheet converter (Python Notebook for converting L2 spreadsheet to OCL Bulk import format): https://github.com/jamlung-ri/WHO-SMART-Guidelines/blob/main/WHO%20Measles%20Dictionary%20Parsing%20and%20OCL%20Prep.ipynb
  • Converts DAK spreadsheet concepts into OCL bulk import files that create a single source, then organizes concepts into value sets, then creates versions of those value sets
• I-TECH L3 tooling (not yet endorsed, further documentation needed): https://github.com/I-TECH-UW/who_l3_smart_tools/

Using OCL terminology resources for FHIR IG generation

As of August 2024, OCL is not currently established as a terminology server for the FHIR Implementation Guide (IG) publisher. This means that the IG Publisher cannot directly query OCL's FHIR terminology resources during the IG However, OCL's terminology resources can be used in combination with the IG Publisher (including FSH/SUSHI files if needed) to generate a FHIR implementation guide.

Retrieving FHIR resources from OCL

One of two main methods can be used to get FHIR terminology resources out of OCL. Regardless of which option is used, OCL's FHIR resources (CodeSystems, ValueSets, and ConceptMaps) need to be saved individually, not as FHIR bundles.

Method 1: Get as FHIR bundle and extract out individual FHIR resources

OCL's API returns a bundle of resources when hitting appropriate endpoints for CodeSystem, ValueSet, and ConceptMap. In general, this should occur in the organization namespace in which the DAK dictionary was authored. Additionally, parameters can be specified to filter out the resources that are returned in the bundle.

The generic structure for these API requests is:

https://fhir.[environment.]openconceptlab.org/orgs/[OCL Organization ID]/[FHIR resource to retrieve]/?[attribute to filter by]=[value]

An more common example for these API requests in the context of SMART Guidelines is:

https://fhir.staging.openconceptlab.org/orgs/WHO-SG-Example/CodeSystem/?purpose=Example

This queries OCL's Staging server, looking in the "WHO-SG-Example" organization, getting the CodeSystem resource, but restricting to only CodeSystems with the "Purpose" attribute as "Example".

Using this query structure, you can retrieve all of the appropriate terminology resources in three queries: One for CodeSystem resources, one for ValueSet resources, and one for ConceptMap resources.

• Note: be sure to check that all expected terminology resources are in the bundle. If any are missing, check that all OCL repositories have a saved version (i.e. not the HEAD version).

Once the resources have been retrieved, tooling like this Python script can be used to parse out the individual FHIR resources from the bundle. These resources should now be in their own individual JSON files, which can be used in subsequent steps.

Method 2: Download and save FHIR resources individually

OCL's API can also return an individual FHIR terminology resource as its own JSON file, which can be saved off one-at-a-time.

The generic structure for these API requests is:

`https://fhir.[environment.]openconceptlab.org/orgs/[OCL Organization ID]/[FHIR resource to retrieve]/[OCL Repository ID]/`

A more common example for these API requests in the context of SMART Guidelines is:

`https://fhir.staging.openconceptlab.org/orgs/WHO-SG-Example/ValueSet/danger-signs/`

JSON files can be saved from your browser, Postman, Python, Google Sheets, or various other tools.

Once all the resources have been saved, they should be in their own individual JSON files, which can be used in subsequent steps.

Preparing terminology resources for the IG Publisher

Place the FHIR resources into the GitHub repository that contains the other IG files, specifically in the subfolder "input/resources/"

After other L3 artifacts (CQL logic, FSH files, etc.) have been placed in the GitHub repo, the FHIR IG can be generated.

• Note: Other L3 artifacts can reference FHIR terminology resources from OCL (e.g. In a FSH file, bind a profile element to a ValueSet that came from OCL), following a similar workflow as if the terminology was being authored in FSH files. Use the terminology resource's Canonical URL attribute for this, such as the example FSH file shown below:

Profile: CatMeaslesImmunization
Parent: SGImmunization

* extension[administeredProduct]
  * valueCodeableConcept from http://smart.who.int/immunizations-measles/ValueSet/VSMeaslesVaccineProducts (required)
  // * valueReference only Reference(CatMeaslesVaccineProduct)

• In this example, the canonical URL "http://smart.who.int/immunizations-measles/ValueSet/VSMeaslesVaccineProducts" references this OCL valueset.
  • Note: OCL enables searching by a canonical URL if you would like to verify the presence of a terminology resource in OCL. Example search in the OCL Staging environment.

Dictionary Checklist

The following tables display the required and optional attributes to be present when developing terminology artifacts for DAK dictionaries. Some of these attributes are required to create something within OCL, but all attributes in the Required section will be needed to publish the completed DAK to the SMART Guidelines community.

DAK Dictionary (Source)

Many of the attributes specified in the DAK source will appear in the FHIR CodeSystem resource(s) once the DAK dictionary has been authored and getting ready for L3 publication.

Required

Optional but recommended

Concept Attributes

Many of the attributes specified in these concepts represent columns from the L2 data dictionary spreadsheet.

Required

When creating concepts (data elements or input options), the following OCL fields should be populated (using these values from the DAK data dictionary if available):

Optional (but recommended)

Additionally, the following attributes from the DAK can be defined as Custom (AKA Extra) Attributes in OCL if applicable:

Value Sets (Collections)

Be sure to include "Purpose" attribute as the main DAK attribute?

Many of the attributes specified in the DAK collections in OCL will appear in the FHIR ValueSet resource(s) once the DAK dictionary has been authored and getting ready for L3 publication.

Required

Optional