Guidance on this page was more broadly focused. With the immediate need to support IG developers, this page has been simplified on the child page here: Terminology Expectations for IG Developers (Simplified)

Note that this page is in development and not a set policy. 

Our goal is to:

1. Agree to guidance changes displayed below, and update them in the FHIR specification
2. Develop the lightweight process for IG developers to add placeholder on Pending tab of THO through a Pro Forma process that requires only the submission of field elements, and document process
3. Develop process for TSMG to approve code systems that will NOT be added to THO
4. Follow up with FMG to determine IG validation process that is implemented to support the expectations and ensure they are documented
5. Vocab needs to provide guidance on when value sets should be added to THO and ensure that we encourage sharing

Updates to FHIR specification 

http://build.fhir.org/terminologies.html#system

Existing text is below with additions from discussion during May 2022 - HL7 WGM - Tuesday Q5 Minutes Joint with FHIR-I and M&M. 

Open questions are listed in pink text. 

4.1.2 Choosing a system 

When constraining coded data in a FHIR profile, the IG developer needs to establish a value set binding. The value sets used in an IG reference codes from a code system which must be documented in the system parameter of the coding of a codeableConcept.

The URL in a system is always a reference to a code system, not to a value set. The system ensures that codes can be traced unambiguously back to their original definition, and that logical comparisons, matching and inferences can be performed consistently by different systems by operating on this code in the context of its code system. For this reason, choice of the correct URI for the system attribute is critical.

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

• Terminology.hl7.org  (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 it intended to be used for the same purpose, reference the section on modifying code system content below.
  • Check the External Code Systems and HL7 Code Systems tabs
• 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. 
  • If the code system is external to HL7 (e.g. SNOMED CT, LOINC), the CodeSystem identifier authorized by HTA SHALL be used.  
    • Follow the HTA defined process for Validating and Requesting Identifiers for External Code Systems and Identifier Systems to determine the identifier or request one if not already validated by the HTA.
  • If there is not an external code system that satisfies your use case, you may need to create a new internal code system. 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 seeking 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: http://terminology.hl7.org/CodeSystem/xxxxx (where xxxx is a meaningful text string)
      • This will start the process to create a NamingSystem resource in terminology.hl7.org for your CodeSystem
      • The CodeSystem content may remain within the IG 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 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,
      • 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 and reference the CodeSystem in THO.
  • If the code system is intended to never be used in a production system and is believed to be IG-specific for all time, or will be used to create a value set bound with Example binding strength, 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. 
    • If the example concept codes will be used in multiple IGs, (should URL be anchored in THO just in case it moves there in the future?)
      • Use the following URL pattern: [ig-base-canonical]/CodeSystem/example-xxxxx (from one of the multiple IGs, there is no reason to define the same example CodeSystem in multiple IGs)
    • If the example concept codes will only ever be used in a single IG:
      • Create an identifier following this pattern: [ig-base-canonical]/CodeSystem/example-xxxxx (where xxxxx is a specific string that conveys intent)
  • What about case where it’s totally unknown where the codes will live eventually or we know the codes should eventually be added to an existing HL7 code system via the UTG process? Specifically URL guidance

For publishers of code systems, the following considerations should be kept in mind when defining the correct URI to use:

• Once defined and in production use, in rare situations, the code system URI may change. Implementers should design their system to support a code system identifier change. Terminology.hl7.org implements NamingSystem resources to manage code system identifiers and their effective date range.
• An http: address SHOULD resolve to some useful description of the code system. Ideally, if a user makes a request of the address with the media type set to a FHIR media type, the server will respond with a CodeSystem resource, but some other human or computable definition is allowed
• HTTP addresses should be permalinks which may re-direct to more information regarding the particular code system browsable in a traditional web browser
• A scope of the code system URI and the correct usage of codes and displays in its namespace will be clearly defined by HTA. See examples for SNOMED CT , RxNorm , LOINC , NDC 
• All code systems internal to HL7 and maintained in THO use Terminology.hl7.org  as the base (How about for IG-specific code systems?). Generally, allocation of URLs is hierarchical, and most care is required in choosing the Base URL.
  • The url pattern is: terminology.hl7.org/CodeSystem/xxxxxx/xxxxxxx (Pointing out that this pattern is problematic in THO)

Note: if the code system is made available packaged inside a ValueSet resource, the correct URL for the system value is ValueSet.codeSystem.system, not ValueSet.uri.

4.1.2.1 Modifying code system content (New Section)

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 Terminology.hl7.org , 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.

4.1.4.? Defining Value Sets (New Section)

Value set bindings are established when constraining coded data in a FHIR profile or Implementation Guide (???). However, value sets may also be maintained in the FHIR Base specification, THO, or a library IG. 

Value sets should be defined and maintained in an Implementation Guide if dependent on a code system that is defined and maintained in the IG.

Value sets that are not using code systems defined by the IG should be defined and maintained within the IG but at FMM3 they should be strongly considered for promotion to THO, where the criteria should be value outside of IG.

Value sets should be defined and maintained in the FHIR Base specification 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 if:

• The value sets have wider applicability
  
  • They may alternatively be defined in a library IG (e.g. public health library or US core)
• The definition of the value set includes all codes from a code system that lives in THO 
• The definition of the value set is non-trivial (e.g. All codes from 'x' is trivial) and it is likely to be used across multiple products
• The definition of the value set is immutable (i.e. the definition can't be changed) or the steward is comfortable allowing the definition to be managed through the THO process

IG Validation Checks

• Check to see if code system is recognized (i.e., a CodeSystem instance in THO, tx.fhir.org, or NamingSystem in THO)
  • Throw warning if not recognized and not based in "http://example.org"
  • Throw warning if url is in THO but not the content (FMM3+)
  • 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, no ‘temporary’ in URL. Warning can be suppressed if THO has approved exception.