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' (including the Metadata Record tab) and  'HL7 Code Systems'  on  (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 , 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 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 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 ""
        2. The canonical URL SHALL follow this pattern: (where xxxxx is a meaningful text string). 
        3. This will start the process to create a NamingSystem resource in for tracking the identifier(s) 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 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. “[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.