Page tree
Skip to end of metadata
Go to start of metadata

Using and Creating Terminology Codes or Code Systems

Note: All product families are assumed to be covered by the policies in this document.

The correct code and code system can be determined by working through the following list, in order:

  1. Determine if an existing Code System can be used
    1. Check the 'External Code Systems' (including the Metadata Record tab) and  'HL7 Code Systems'  on Terminology.hl7.org  (THO). 
      1.  If the code system is listed in THO
        1. If the THO code system contains the code(s) required, the canonical CodeSystem URL SHALL be used. Use of existing code systems is advised whenever possible.
        2. If the THO code system does not contain codes(s) required by the IG
          1. If required codes for IG are within the scope of the existing code system, proceed to Step 2 on determining where a code should go
          2. If required codes for IG are not within the scope of the existing code system, proceed to Step 3 on creating a new code system
      2. If the code system is not listed in Terminology.hl7.org , determine which case listed below applies to the code system and work through the process for the appropriate case. 
        1. If there is an external code system that satisfies the use case,
          1. implementers SHALL follow the HTA defined process for Validating and Requesting Identifiers for External Code Systems and Identifier Systems to request one if not already validated by the HTA.
        2. If there is not an external code system that satisfies the use case
          1. Proceed to Step 2 below
  2. If you are confident that no existing external Code System or existing internal HL7 code system contains the content you need, you will need to create a new code and possibly a code system for the concept(s)
    1. Evaluate where the code *should* go.  The following items should be contemplated, in preferential order:
      1. Does it fall within the scope of an existing external code system where there might be a chance of adding it to that code system? 
        1. Note that some external code systems are static and can’t realistically have new codes added. Additionally some are proprietary and suggested changes would need to follow the external code system owners processes
      2. Does it fall within the scope of an existing HL7-managed code system as found in THO?
        1. Some examples of existing code systems that may include relevant content include ActCode, ActClass, RoleCode, RoleClass.
      3. Is it a concept (or set of concepts) that will require a new code system appropriate for sharing in THO? 
      4. Is it so tightly tied to the structures or usage of the IG that it cannot evolve without a new publication of the specification? OR will it ONLY will be used to create a value set bound with Example binding strength?
      5. For low-maturity resources (e.g. FMM 2 or less for FHIR), is determining where the codes should go not yet known?
    2. Once you have evaluated where the code should go, follow the workflow in Step 3 below.
  3. Determine if the code(s) is sufficiently well defined (for FHIR this means FMM3+ of the FHIR resource type or the IG if available) that adding the code(s) to the desired end code system and subjecting them to “good terminology practices” around adjusting code symbols, definitions and display names is appropriate
    1. If no (your IG is not yet mature) and the target for the code system is a new internal THO code system (i.e. option 2.a.iii above):
      1. Add the code system name and identifier (URL) to THO using the lightweight process in UTG (need link to process once created)
        1. Upon adoption of this process by HL7, ALL HL7 defined code systems SHALL have an anchor of "http://terminology.hl7.org/CodeSystem/"
        2. The canonical URL SHALL follow this pattern: http://terminology.hl7.org/CodeSystem/xxxxx (where xxxxx is a meaningful text string). 
        3. This will start the process to create a NamingSystem resource for tracking the identifier(s) in terminology.hl7.org for your CodeSystem
        4. The CodeSystem resource content SHOULD be created and maintained via the initiating IG build process until stable enough to be moved to THO. Define concepts and codes for the code system within the IG until confident the concepts will not change or when ready to seek approval/publish a FHIR IG at FMM3. See step 3.d.iii once ready to move to THO.
    2. If no (your IG is not yet mature - for FHIR, below FMM3) and the target for the code system is a IG-specific code system (Option 2.a.iv above):
      1. Seek TSMG approval (need link to process once created)
      2. Define the code system within your own specification with a canonical URL specific to your specification
    3. If no (your IG is not yet mature) and the code system is something other than a THO or IG specific code system (Option 2.a.i, 2.a.ii or 2.a.v above):
      1. A temporary code system SHOULD be defined within the referencing specification with a canonical URL that explicitly includes the word “temporary” and is marked as 'experimental'.  E.g. “http://hl7.org/[yourspecpath]/CodeSystem/temporary”  (Typically, all ‘temporary’ codes within a specification will be lumped into a single temporary code system.)  The definition of the code system SHALL make clear that the codes WILL change and be migrated elsewhere in a future release.
        1. If the target for the code is a code system external to HL7 (Option 2.a.i), requests for new content should be made directly with the code system steward. The process for making content requests for external code systems varies widely between code systems and information about the process is often made available through the publisher's website. Information for making concept requests is also located on the HTA Confluence pages. The HTA will assist with the creation of requests for new content and content changes for International Code Systems (such as SNOMED CT and LOINC) required for HL7 international standards. More information can be found on the Request Content in External Terminologies page. 
        2. TODO: If the target for the code is a code system internal to HL7
    4. If yes (i.e. Your IG is at level FMM3+), the codes SHALL be added to their official code system prior to publication
      1. For external code systems (2.a.i), engage with the relevant terminology source, ideally working through the TSMG to request addition of the codes.  If ‘temporary’ codes were created in the IG, remove them.  Update value sets to point to the canonical URL of the external code system.
      2. For existing HL7 code systems (2.a.ii) use the UTG process to add the codes to THO.  If ‘temporary’ codes were created in the IG, remove them.  Update value sets to point to the canonical URL of the HL7 code system.
      3. For new HL7 code systems (2.a.iii), migrate the code system initially defined in your IG with the THO naming system into THO using the UTG process.  Value sets will not need to change because the canonical URL will remain the same. OIDs should be created for HL7 created artifacts. You will need to rebuild the initiating IG once the code system is included in an official publication of THO and the resource is removed from that IG. 
      4. For specification-specific code systems (2.a.iv), continue as before, suppressing any QA warnings with a reference to your TSMG approval.
      5. If you are unsure of where the codes should live (2.a.v), by this point you must determine a final resting place for your concepts.  Work with the Vocabulary workgroup and follow the appropriate steps above based on the chosen terminology location.  For FHIR, artifacts SHALL NOT progress past FMM2 without determining a permanent code system for their codes.
      6. The color of the M&M is purple.

Value sets may be maintained within the IG, FHIR core, THO, VSAC, or a library IG. Use of existing value sets is advised. If there is not a value set that satisfies your use case, you may need to create a value set. Use the guidance below to determine where the value set should be defined and maintained. If an organization is making a realm-specific guides and specifications, that realm may specify a facility like VSAC for reference content. Note: affiliates may declare other valid sources of content in the future. 

Value sets should be defined and maintained in an Implementation Guide if:

  • The definition of the value set is dependent on a code system that is defined and maintained in the IG. 
    • However, if the code system is moved to THO, the value set should also be considered for promotion to THO where they are likely to provide value outside of the IG.
  • Note that it is presumed that the default for value sets is to define and maintain them within the initiating IG because:
    • It is expected that IGs deal with domain-specific needs that do not extend beyond the IG
    • Early in the creation process value sets are best maintained within the domain knowledge of the IG authors.
    • BUT, broader use should always be considered by IG authors with every new ballot or publication such that some value sets may be considered for THO promotion. This is particularly true once the value set reaches FMM 3.

Value sets should be defined and maintained in FHIR core if:

  • They are 'schema bound' (including their matching code system). This means the value set is bound to a FHIR element with a required binding, and only changed by ballot on FHIR itself.
  • They are purely illustrative/example bindings, but these should be clearly labelled.

Value sets should be defined and maintained in THO or VSAC if:

  • More than one IG specifically references the value set and there is no common dependency IG that is an appropriate home for the value set.
    • They may alternatively be defined in a library IG (e.g. public health library or US core) but doing so is a more complicated and less general approach because these value sets are not as visible to the community.
  • The value sets are thought to have wider applicability (beyond the initiating IG) now or in the future.
  • The definition of the value set includes all codes from a code system that lives in THO.
  • The value set is FMM3 or higher.

IG Validation Checks

  • Check to see if code system(cs) is recognized (i.e., a CodeSystem instance in THO, tx.fhir.org, or NamingSystem in THO)
    • Publisher should generate an ERROR if one of the following two is not true: 1) the code system url is in THO, or 2) the code system resource is defined in any included IG that the build IG references.
    • Error if url does not have stem "http://terminology.hl7.org/CodeSystem/" and not listed in external code systems in THO, or not based in "http://example.org"
    • Warning if cs resource not in IG build or not in THO publication (true either internal or external cs)
    • Warning if Internal HL7 cs with FMM3+ is not in THO unless TSMG approved
    • Throw error if ‘temporary’ in url if FMM3+ 
    • Throw warning if code system defined in IG and no NamingSystem in THO, and no ‘temporary’ in URL. Warning can be suppressed if TSMG has approved exception.
  • No labels

7 Comments

  1. The above doesn't account for the scenario where an author might want to use an HL7 internal code system that is not listed in THO. I imagine this will happen less and less, but might be worth considering.

  2. Comment from Joanie Harper who can't comment due to some permissions errors: 

    In order to balance 1.a.i with 1a.ii, suggest that 1.a.i change to :

        1.  If a code system is listed in THO
          1. If the THO code system contains the code(s) required, the canonical CodeSystem URL SHALL be used. Use of existing code systems is advised whenever possible.
          2. If the THO code system does not contain codes(s) required by the IG
            1. If required codes for IG are within the scope of the existing code system, proceed to subsection 2 on determining where a code should go
            2. If required codes for IG are not within the scope of the existing code system, proceed to subsection 3 on creating a new code system
  3. "2. If an existing external Code System cannot be used and you are confident that no existing internal HL7 code system contains the content you need, you will need to create a new code and possibly a code system" –

    • We need to request that if someone is confident there is a gap as described above, a Jira ticket should be entered and tracked/approved. 
    1. Done...all the proceeding items in Step 3 that require JIRA tickets have it noted

  4. From WGM - Regarding 3.a.i.3 - namingSystem resources are not visible at THO. TSMG to consider if this needs to change (though not a barrier to this policy being published)

    1. namingSystem resources are visible in THO, and those specific to this policy will be added to the Pending tab in THO. 

      Examples of namingSystem resources are the external code system identification records here: http://build.fhir.org/ig/HL7/UTG/external_terminologies_csti.html