Terminology Expectations for IG Developers (Draft For TSC Consideration)

Using and Creating Terminology Codes or Code Systems

Using and creating terminology codes or code systems as part of developing an IG may not always be straightforward.  This policy as stated below aims to address the majority of scenarios in which creating and using terminology, codes or code systems are required.  If in the initial development or future enhancement of an IG you are unable to apply this policy, please contact the TSMG at tsmg-cc@lists.hl7.org.

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. Your answers to these questions will be used in section 3 or 4.
      1. Does the concept 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 the concept 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 the concept a concept (or set of concepts) that will require a new code system appropriate for sharing in THO? 
      4. Is the concept so tightly tied to the structures or usage of the IG that it cannot evolve without a new publication of the specification?
      5. Will the concept ONLY be used to create a value set bound with Example binding strength? 
      6. Is the concept used only within a low-maturity resources (e.g. FMM 2 or less for FHIR)? 
   2. Once you have evaluated where the code should go, follow the workflow in Step 3 below.
3. When the concept and code system are not mature (IE: concept is minimally defined) then based upon your answers to section 2 above:
   1. If the answer to 2.a.ii is YES, you will create a new internal THO code system. Use the follow instructions:
      1. Add the code system name and identifier (URL) to THO using the process in UTG (for more information, see Vocabulary Maintenance at HL7)
         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 the answer to 2.a.iv is YES and the target for the code system is an IG-specific code system:
      1. Seek TSMG approval via an email to the tsmg-cc@lists.hl7.org
      2. Define the code system within your own specification with a canonical URL specific to your specification (for example: https://build.fhir.org/ig/HL7/US-Core/CodeSystem-us-core-documentreference-category.html)
   3. If the answer to 2.a.v is YES, then the concept and code system is IG-specific and should never be used in production systems.
      1. Add the code and code system to your IG and do not add to THO.
      2. If a new code system is created, then the name SHALL end in the string "Example" to clarify that the code system is only to be used for example bindings.
   4. If the answer to question 2.a.i, 2.a.ii or 2.a.vi  is YES and the code system is something other than a THO or IG specific code system:
      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. 
4. When the concept and code system are to be used in a mature resource (i.e. Your IG is at level FMM3+), the codes SHALL be added to the 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 and 2.a.v), 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.vi), 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.