Open Questions for TSMG to Consider/Resolve

  1. Need clarification from FMG on FMM levels
  2. Need to define process for requesting exception from TSMG
    1. Suggest Jira project like HTA uses 
    2. Need to also prevent duplicates for exempt urls (could point to these from THO).  Duplicates would be prevented through employ of established process (JIRA tickets and tooling once this is developed) to deny creation of duplicate URIs.
  3. Need to define 2 step process for adding name/url to Pending tab
  4. We need to confirm that we have all external code systems metadata records for that are in in THO. All HL7 code systems should be in THO
    1. RH will be checking into this per 29Nov22 TSMG call
  5. Need to ensure everything in THO has an OID (and one is created for everything new)
    1. Any new HL7-created artifact should have an OID assigned
  6. If all HL7 authored (in an HL7 aligned IG) code systems (cs) will have a THO stem concatenated to the IG-chosen name, we must determine if it is our problem to ensure that url is globally unique across all IGs, options discussed include
    1. Use task force approach of creating naming system to hold name/url in Pending tab
      1. This requires tooling to check THO git for duplicates. Presume either:
        1. at time of CS creation (post resource into IG's git?) by author - not sure what tooling could support this.
        2. at IG build and throw error (based upon some sort of comparison against cs and ns resources in THO git)
      2. Might also need to link to the code system within the IG (its temporary home) - to provide link to actual content
    2. Include IG name in the canonical such as
      1. Could still include in Pending tab if there is a tool to comb IGs for the content?
    3. See if we can use tooling to create database of cs urls "for all IGs". Then
      1. when any IG is built using the HL7 publisher and have the publisher cross-check this DB and a warning can be thrown if duplicate exists
      2. Could create an FHIR git-crawl to make the initial DB load. Obviously this means we will miss those not found.
      3. There will be a possibility for duplicate cs with the same THO stem ( Duplicates would never be ok. 
      4. Reuben suggests the Work Groups should provide the urls already in use across their IGs so that we can make them known in THO (but these are likely not anchored in THO)
  7. Determine how example code systems and value sets should be handled
    1. GG and LM believe these should live in FHIR, others already exist in THO 
    2. Suggestion: If IG creates code system and only binding is example, then it must have 'example-' in the id and be anchored in THO or throw error
    3. RD / LN / CM suggesting that these examples are in the context of an IG for all product families and should this not be in THO but remain as a part of the IG
  8. Follow up with appropriate changes needed in FHIR core 
  9. Need tooling support to help implementers more easily identify content that meets their need to prevent the creation of duplicate resources

Using and Creating Code Systems

The correct value to use in the system for a given code system can be determined by working through the following list, in order:

  • Check the 'External Code Systems' and 'HL7 Code Systems' tabs on  (THO). 
    • If a code system is listed here, the canonical CodeSystem URL SHALL be used. Use of existing code systems is advised.
    • If an existing code system is missing content required by the IG but is intended to be used for the same purpose, reference the section on modifying code system content below.
  • If the code system is not listed in , determine which case listed below applies to the code system and work through the process for the appropriate case. 
    • If the code system is external to HL7 (e.g. SNOMED CT, LOINC), the CodeSystem identifier authorized by HL7 Terminology Authority (HTA) SHALL be used.  
    • If there is not an external code system that satisfies your use case, and you are confident that no existing HL7 code system scopes the content you need, you will need to create a new internal code system.
      1. Ensure existing code system does not exist. Some examples of existing code systems that may include relevant content include ActCode, ActClass, RoleCode, RoleClass.
        1. If content of an existing HL7 code system scopes the area but new concepts are needed, submit new concepts via the UTG process  to the identified code system. 
      2. Once you determine a new code system is needed, if you strongly suspect it will always be an internal code system and not be supported by an external code system, follow the 2-step UTG process  for code system definition in THO. Both steps must be complete prior to going to ballot seeking FMM3 or publishing at FMM3. 
        • Add the code system name and identifier (URL) to THO using the lightweight process in UTG (need link eventually)
          • The canonical URL SHALL follow this pattern: (where xxxx is a meaningful text string). 
            • Upon adoption of this process by HL7, ALL HL7 defined codes systems SHALL have an anchor of ""
          • This will start the process to create a NamingSystem resource in for your CodeSystem
          • The CodeSystem resource content may 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 at FMM3.
        • When the CodeSystem is at a state where the IG authors/developers/interested parties are confident it is sufficient, and as early in the process as possible, the resource content SHALL move to THO (and therefore deleted from the initiating IG build):
          • Start the UTG process  to move the CodeSystem content to THO.
          • Set yourself as a watcher on the UP JIRA ticket and update your specification when your CodeSystem is in THO.
          • Once the CodeSystem is established in THO, remove it from the IG.
          • This process will not require any change to the value sets or other material that reference the code system because the url will not change. 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. 
    • If the code system is one of the following two situations it SHALL get approval from the Terminology Services Management Group (TSMG) (add link to approval process here once it exists) to maintain code system concepts in the IG and qualify for an exception to the best practice of maintaining internal terminology artifacts in THO at FMM3. Note the canonical URL SHALL follow this pattern: . (where xxxx is a meaningful text string) even if it is to remain in the IG
      1. Intended to never be used in a production system and is believed to be IG-specific for all time, or 
      2. ONLY will be used to create a value set bound with Example binding strength.
    • Any new HL7-created artifact should have an OID assigned. 

It is possible that the selected system is missing content required by an IG. It is best practice to add or modify content (such as concepts) in an existing code system rather than create a duplicative code system with the required changes, as long as the content modifications align with the purpose of the code system.

If the code system is external to HL7, 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) required for HL7 international standards. More information can be found on the Request Content in External Terminologies page. 

If the code system is internal to HL7 and anchored in , content can be modified via the UTG process . The request will go through a Consensus Review process prior to the proposed changes being added to THO.

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 an 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.
    • 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 is recognized (i.e., a CodeSystem instance in THO,, 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 "" and not listed in external code systems in THO, or not based in ""
    • 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+ (only applies to external code systems)
    • 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


  1. CMG Review the proposed guidance and provides the following requested changes:


    Change: Value sets may be maintained within the IG, FHIR core, THO, or a library IG.

    To:  Value sets may be maintained within the IG, FHIR core, THO, VSAC, or a library IG. 

    Rationale - for CDA IGs, value set content and expansions have traditionally been managed in VSAC and a tremendous investment has already been made in using this tool.  We need to allow (grandfather in) for this need.


    Change the order of the three guidance statements to be:

    1. Value sets should be defined and maintained in THO and allow VSAC if: (note, this should cover the majority of cases)

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

      1. Note to remove the statement "it is presumed that the default for value sets is to define and maintain them within the initiating IG"
    3. Value sets should be defined and maintained in FHIR core if:  (note for CDA R2 the value sets for the base spec are listed in THO for convenience, but for CDA R2.1 the value sets currently only are in the core spec.)

    1. these comments were addressed in the 29Nov22 TSMG meeting & text above changed to reflect discussion

  2. Need to clarify what FMM3 applies to (IG or artifact). Is there a loophole that an artifact at FMM3 could point to a lower-maturity artifact in another IG that doesn't meet the expectations defined in this document?

    And - will the maturity model change based on Proposed HL7 Specification Maturity Model?

  3. Under "Modifying Code System Content", it is noted that "If the code system is external to HL7, requests for new content should be made directly with the code system steward." However, looking at HTA guidance, it looks like HTA mediates this process, rather than assist. Which one is it?

  4. For TSMG-granted exceptions to moving code system to THO, the canonical URL pattern is missing.

  5. Caroline Macumber Reuben Daniels A follow-up to my request (of a few minutes ago)  - this page / version doesn't seem to be the latest for this topic?