Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  1. Determine if an existing Code System can be used
    1. Check the 'External Code Systems' and 'HL7 Code Systems' tabs on  (THO). 
      1.  If a code system is listed in THO and it
        1. Contains the code(s) required, the canonical CodeSystem URL SHALL be used. Use of existing code systems is advised whenever possible.
        2. Does not contain codes(s) required by the IG and
          1. 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. Required codes for IG are not within the scope of the existing code system, proceed to subsection 3 on creating a new code system
      2. 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. 
        1. If the code system is external to HL7 (e.g. SNOMED CT, LOINC), a CodeSystem identifier authorized by HL7 Terminology Authority (HTA) SHALL be used. and 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 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
    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?  (Some external code systems are static and can’t realistically have new codes added)
      2. Does it fall within the scope of an existing HL7-managed code system as found in THO? 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 net 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 ONLYwill 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 resource 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 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 ""
        2. The canonical URL SHALL follow this pattern: (where xxxx is a meaningful text string). 
        3. This will start the process to create a NamingSystem resource in 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 at FMM3. See step 3.d.iii once ready to move to THO.
    2. If no (your IG is not yet mature) 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 target for the code system is something else (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. “[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 should 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. 
    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 net 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 were 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 TSMG if unsure, then follow the appropriate steps above based on the chosen terminology location.  Artifacts SHALL NOT progress past FMM2 without determining a permanent code system for their codes.