Terminology Play Book

This page defines (in FAQ format) a summary of some of the policies that apply to implementation guides developed for publication by HL7 International - either for international use or U.S. realm use, irrespective of product family (i.e. CDA, FHIR, v2 or other).  It is intended as a supplement to the terminology guidance maintained as part of the IG Guidance.

All of the following rules apply only to specifications published by HL7 International, though affiliates or other organizations are free to adopt them as well.

Where should custom code systems be located? 

As discussed in the TSMG's Terminology Expectations for IG Developers policy, the location for custom code systems is determined as follows:

1. IG-specific code systems: If the concepts are so tightly tied to the structures or usage of the IG that it cannot evolve without a new publication of the specification the code system should remain in your IG with a canonical URL specific to your specification. TSMG approval is required for this option.
2. Example code systems: If the concepts in the code system will ONLY be used to create a value set bound with Example binding strength the code system should be maintained in your IG.  The name of the code system SHALL end in the string "Example" to clarify that the code system is only to be used for example bindings and should not be used in production instances.
3. Immature (FMM level 2 or lower) code systems: If the concepts are not IG-specific but are currently of a low maturity the code system itself should be maintained in your IG until such a time as you are confident the concepts will not change or you are seeking to publish your IG at FMM 3 or higher. 
   1. If it is known that eventually the codes will be added to a net new code system hosted in terminology.hl7.org, then the canonical URL SHOULD be pre-established and registered as a NamingSystem instance hosted in THO.  In this case, the canonical URL SHALL follow the pattern: http://terminology.hl7.org/CodeSystem/xxxxx.
   2. If the expected target of the code system is either undecided, or expected to not be terminology.hl7.org (e.g. SNOMED CT, LOINC, etc.) then the canonical URL of the code system SHALL be based on the canonical root of the IG and include the word 'temporary' to indicate to implementers that the URL will change.  As well, the code system SHALL have 'experimental' set to 'true'.
4. Mature (FMM level 3 or higher) code systems: At this point, (unless meeting criteria #1 or #2), the code system content cannot be maintained within the IG any longer and must reside either in an external code system or be maintained as part of terminology.hl7.org.

How do I ask for permission to use an IG-specific code system?

The TSMG handles requests for permission to use an IG-specific code system.  To request permission from them send an email with your request to tsmg-cc@lists.hl7.org

Where should custom value sets be located?

As of right now there is no official policy on where value sets should be maintained.  However, the following is good guidance which will likely reflect the stance that an official policy will take:

• Reusable value sets: A value set is appropriate for re-use if it meets all of the following:
  • It would potentially be useful in specifications other than your own
  • Its purpose is clearly stated and is sufficient to guide future maintenance of the value set definition without input from the project that developed your specification
  • There is sufficient complexity to the value set definition that there is a saving of effort involved in sharing the value set definition
  • The value set is sufficiently stable in its definition that others can rely on it
  • Its purpose is for use in real systems, not just for example use

If a value set meets all of these criteria, then it should be maintained outside the IG:

• • If the value set definition will need to change frequently (based on frequently evolving requirements and/or a need to frequently adjust filters or enumerations based on changes to the underlying terminologies), it should be maintained in a system that enables rapid development of terminology resources such as VSAC (U.S. specifications only).
  • Otherwise, terminology.hl7.org is likely an appropriate home
• Local value sets: In all other cases, the value set should be maintained as part of the specification that uses it with no expectation for re-use (except possibly by other implementation guides that derive from your specification.

What are the rules for binding to value sets with intellectual property restrictions?

HL7 tries to ensure that implementers of its specifications do not incur any additional costs as a result of the need to license additional IP.   For this reason, the FHIR Management Group imposes constraints on the use of value sets that are not freely available.  Other management groups may impose similar policies in the future.  The specific guidelines are as follows:

• Binding to terminologies with an 'example' or 'preferred' binding strength is fine regardless of their licensing requirements, though if the value set is being defined within the HL7 specification, it is necessary that HL7 be licensed to actually publish the value set definition (which may mean listing codes referenced as filters, and should ideally also include the ability to expand the value set).
  • This requirement MAY be worked around by publishing the value set definition in an external tool such as VSAC, though that is less preferred as it makes it harder for implementers to see the list of codes.  (VSAC requires registration.)  Also, VSAC is only useable for U.S. Realm value sets.
• Terminologies that do not require costs to use in the target implementation jurisdiction are unrestricted.  Therefore terminologies such as LOINC and UCUM can be freely used in any specification.  SNOMED-CT can be freely used in the U.S. because there is a national license for SNOMED-CT.  Also, value sets that only include codes from the Global Patient Set SNOMED-CT subset may be freely used in 'universal' specifications because those codes are free for use globally.
• Terminologies that require costs to use in the target implementation jurisdiction are free to use provided that the target implementers of the FHIR specification are already required to be license-holders of the relevant codes for other reasons, typically regulation.  For example, requiring the use of CPT codes in a specification targeted at the payments systems of U.S. payers or EHR vendors who are mandated by regulation to send or receive insurance claims using that code system would be fine because it would not present a barrier to implementation.
• Any other bindings will require FHIR Management Group approval

Approval can be sought by emailing fmgcontact@hl7.org indicating the desired binding and rationale.  The request will then be discussed on an FMG call.