Skip to end of metadata
Go to start of metadata


We have a request from the international community to clarify policy on adding content to older HL7 V3 code systems where the content may be available elsewhere. This arose relative to some Pharmacy content (email chain with Andrea MacLean, Canada Health Infoway). It seems clear that HL7 needs a policy (at least write down what we believe to be true, and formalize it) justifying reluctance to revise content of older HL7 code systems (V2 and V3) where there are internationally recognized and maintained terminologies with overlapping content and are currently in use.

HL7 needs policy statements to include the following:

  • Status of value sets defined by HL7 such as: 
    • deprecated (may be used to support legacy implementations, but not allowed for new artifacts)
    • inactive (available for analysis of historical data)
    • active (currently available for use)
      • active and mutable (use is allowed and modification of the value set is allowed, with versioning)
      • active and immutable (use is allowed, but modifications are not allowed)
  • For deprecated and inactive value sets, replacement value sets shall be specified.  For example: orderableDrugForm replaced by EDQM Phamaceutical Dose Form
  • Do we have the same rules for Code Systems? (note that as of September 2018, there are no HL7 created Code Systems in Version 2)
    • It seems that we must have somewhat different rules for Code Systems than for Value Sets
    • It also seems that the rules for Code Systems will be simpler than those for Value Sets
  • Do we need different rules for V2 Tables?
  • Note that the unified vocabulary model we are moving towards for UTG (V2, V3, CDA, and FHIR) has only three states:
    • Draft (content in development, not ready for use)
    • Active (released and may be used in production)
      • May be qualified (flagged) as Deprecated.  This means that an Active code has a message to the user community that it is scheduled to be Retired in the near or at least foreseeable future.  Note that it is strongly desired that an Active code be flagged as Deprecated for some period of time before it is moved to Retired.
      • Note that in the current HL7 vocabulary model, the Deprecated flag includes the Date of deprecation, and an optional reason for deprecation and eventual retirement. 
      • There seems to be emerging consensus that there should be a ballot process around deprecation and retirement of a Code System.
      • The recommendation is that you can make changes to a deprecated Code System, but the deprecation flag serves as a warning to those requesting changes that it is on a schedule track to be retired.
      • A possible policy is that the Vocabulary WG review the deprecated Code Systems periodically (annually?) and if there has been no activity in the past (two periods?) then it is scheduled for a mandatory review, the result of which may be that it is submitted for retirement.
      • We need to communicate to all workgroups that if a Code System is put into a deprecated state it has the consequence that a clock for a mandatory review for retirement has started.
      • Folks are questioning whether or not to allow changes to deprecated Code Systems.  It was suggested that changes are strongly discouraged and require a compelling reason to make the changes.  We absolutely must have an effective way to tell the community when things are deprecated, and to move a Code System to a deprecated state might require the use of the ballot mechanism as it is the way that we reach out to the entire community with some HL7 change. 
      • Note that HL7 continues to strongly discourage the creation of an HL7 Code System where a freely available code system covering the domain is already available from an external (non-HL7) publisher.
    • Retired
      • Marked immutable, no further changes or support for the content (but still published for reference)

Original email triggering this new effort from June 6, 2018:

Dear HL7 Terminology Authority,

When looking at some of the HL7 code systems and value sets, we know from some conversations at HL7,  that HL7 is no longer maintaining some of these value sets and is no longer adding new concepts and in some cases encouraging implementers to use other code systems that are likely more appropriate.

Pharmacy is one such area. (orderableDrugForm as an example)

We could not find an official statement about this from HL7 to help us advise implementers accordingly in Canada or on your HTA page (

Would you please point me to where I can find this statement from HL7.

Thank you.

  • No labels


  1. Part of email discussion from Julie (June 26):

    What we really need, and what I was hoping the HTA would make (or Vocab WG else) is a clear statement of policy.

    For domain specific terminology, which needs expert input to maintain, we should have a clear understanding that we do not, even under extreme pressure, make changes to those code systems, especially where there are excellent, free to use alternatives. Else we should say clearly what we will maintain and how we expect to get the necessary expert resource to maintain those code systems.

    We will also need somewhere that can folk clearly see those code systems that have been deprecated and those that have not. Is that expected in the new tooling?

    I find it very difficult, even in this thread, knowing the context and knowing in depth the code systems concerned, to be able to work out the exact position of HL7 on these things. I did know it 4 years ago, when we were clear that we were not maintaining code systems such as OrderableDrugForm (having tried hard and failed to get it into an acceptable state to match current thinking in the domain), but we seem to have drifted from that place.

    Please can we have clarity?

  2. From an email discussion with Jim (June 29):

    What is meant by older / legacy HL7 v2 and v3 Code Systems?  At what point does a Code System become static and immutable?

  3. I have added some additional wording and some examples of value set states.  We may want to use states defined by the value set definition specification.

  4. Some thoughts but no conclusions:

    1. I think the only way to enforce user adherence to value set use is by restricting the binding flexibility in IGs that the user is required to use. And then do conformance testing. Anything else we do is simply talk among those in the know, largely ignored by folks not attending HL7.
    2. For those creating IGs, we are discussing the provision of guidance on what value sets are to be nailed down per #1. 
    3. Even as involved as I am, I struggle to understand how to clearly communicate how "deprecated" is to be used. At a minimum I think it is a kind of Active. If not, then I'm not sure how it's different from Inactive where Inactive is still available for downloading (ie: it's not Deleted.) In short, I'm not sure Deprecated makes sense for value sets.
    1. The scope of this is not to dictate implementation requirements, just to document a policy on the maintenance and evolution of HL7 defined value sets.  So we are not trying to enforce adherence to proper use.  The binding of value sets to an IG is informed by this policy, i.e. do not bind to inactive or deprecated value sets.

      If we adopt the HL7 policy for deprecation, then a value set in the deprecated state is in the queue for inactivation and that this is a "warning" that the value set is scheduled to be replaced by another value set and users should move to the new value set.  If I remember correctly for version 2.x, a deprecated field is retained for two releases (e.g. deprecated in v2.8, inactive in v2.10).  I would use the same notion for HL7 value sets.

  5. Does it make sense to have separate policies for Code Systems and Value Sets - take a phased approach and address Code Systems first?

  6. Actually code system concepts are going to be different because you can use an inactive code by referencing the code system version when it was active. We do this all the time when building value sets that must find old records with codes that subsequently became inactive. I don't think value set use and behavior is the same. But I'm not confident of how any of this should work let alone how it currently works.

  7. Unknown User (andrea_maclean)

    I met with Carol and Jim at the SNOMED International meetings to help further articulate the request of Canada.  I am simply looking for a statement from HL7 International about past decisions that have already been made, but are not well known or documented.

    I understand that further work is required to develop policies and procedures related to some of the other issue raised here, but right now, I am just looking for a statement that advises net new implementers of vocabulary to "steer clear" of retired HL7 code systems.  

    I have drafted the following to help further articulate my request.  Wordsmithing is welcome.

    Notice of Inactive HL7 Code Systems.


    • It should be noted that effective <insert date here> HL7 is no longer maintaining (adding, changing or deprecating content) from the following HL7 code systems:
      • List here
      • List here
      • List here
    • For existing implementers of these inactive code systems, HL7 respects the right of active implementations to determine the appropriate course of action, if any.
    • For net new implementers, HL7 strongly advises against the adoption and use of these code systems and value sets and recommends that implementers look to other vocabularies or reference terminology that better support the clinical and/or business requirements.
    • HL7 will:
      • no longer add new content to these code systems or their respective value sets
      • no longer maintain or deprecate content in these code systems or their respective value sets
      • not provide maps of these legacy code systems and/or value sets to newer vocabularies as it is impossible to verify the accuracy of the mappings or correct semantics without knowing all the details of any clinical and/or business implementation; to do so, may lead to patient safety risk(s)
      • continue to publish these code systems and value sets to support legacy implementations 

    Please note that further work is being done in the Vocabulary work group to determine the go forward policies and procedures related to the larger issues surrounding code system and value set maintenance.

    Input and participation into the development of these policies and procedures is welcome.

    Please let me know if further clarification of my request is required.

    Thank you.