Page tree
Skip to end of metadata
Go to start of metadata

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. 

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.  
    • 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,
      • 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.

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.

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.

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.


  • No labels

5 Comments

  1. I think we can simplify this by expecting any new code system to have the THO base independent of where the resource is maintained and published. Can we reconsider this as a process and then see if we can make some simple tool to allow authors to create them and we track them in a spreadsheet while we get THO tooling up and running? Then have FHIR publication look at our DB as one of the validation checks?

    This would allow us to push for all systems using the THO url unless example. Then the valid action question is where is it, not how is it structured. 

  2. Is the intent of this to only discuss CodeSystems? Do we need something similar for ValueSets?

    1. Bryn Rhodes The intent here is to focus/discuss CodeSystems. Once we can agree on CodeSystems, the plan is to have Vocab weigh in on when a ValueSet should be shared (added to THO).

  3. Lloyd McKenzie 's input on the policy from email on 2022-10-06:

    Anything FMM2 or lower generally shouldn't be in THO, though a WG can voluntarily choose to register the URL in THO if they have high confidence that the content will eventually live in THO as a distinct code system.

    The default presumption for value sets is that they don't belong in THO even when they're higher maturity.  A value set is only a candidate for THO if:

    - the definition of the value set is non-trivial.  (E.g. All codes from 'x' is trivial)

    - the definition of the value set is immutable (i.e. the definition can't be changed by anyone later) or the work group is comfortable allowing the definition to be managed through the THO process instead of the IG maintenance process

    - there is a stronger argument for non-trivial value sets being in THO if they are likely to be used across multiple products

    For code system content that is FMM3+, the TSMG needs to approve any IG-specific code systems that are not bound to 'code' elements.  Otherwise, the codes are expected to be migrated to external code systems (e.g. LOINC, SNOMED, THO).  If in THO, this could be a new code system or adding codes to an existing one.

  4. Grahame Grieve 's input on the policy from email on 2022-10-06:

    well, here's my understanding of the policy:

    For the FHIR Base specification

    * codeystems and their matching value sets can be defined in FHIR not THO if they are 'schema bound' - that is, bound to a FHIR element with a required binding, and only changed by ballot on FHIR itself

    * they can also be defined in FHIR not THO if they are purely illustrative/example bindings, but should be clearly labelled 

    For FHIR IGs:

    * value sets should be defined in the IG unless there is a judgement call that they have wider applicability (made by the committee in consultation with vocab/TSMG). They may alternatively be defined in a library IG (e.g. public health library or US core), or in THO 

    * code systems should not be defined in the IG unless there is a judgement call that they (a) can't come from elsewhere and (b) do not have wider applicability (made by the committee in consultation with vocab/TSMG, and TSMG has veto). They may alternatively be defined in a library IG (e.g. public health library or US core), or in THO 

    And as Lloyd says, these rules don't apply earlier in the development cycle, though I think it's good for an IG to conform to these by the time it goes to ballot