This is the place to find information on the maintenance of vocabulary at HL7 including the Unified Terminology Governance (UTG) process and operations:
- sign up to watch proposals for changes in vocabulary;
- comment on proposed changes; and
- vote on proposed changed
All of the Code Systems and Value Sets for the Code Systems that are not ballot-bound are maintained through this UTG process as of Q2/Q3 2020. For a list of ballot-bound Code Systems and Value Sets, click here.
HL7 maintains multiple terminologies - v2, v3, CDA value sets and FHIR(R).
The ongoing maintenance of these terminologies is resource intensive and quite opaque to much of the community and as a result, a need for a uniform vocabulary governance process or strategy across all the HL7 product lines was identified. The growing popularity of HL7 FHIR(R) and the associated implementation guides and the increase in participation of the FHIR Community escalated the need for such a process.
There is a need to maintain the terminologies that support all of HL7’s products (v2, v3, FHIR, CDA, etc.) in a way that is responsive and improves quality while reducing the resources that both HL7 and its' volunteers put into the process. As well, there’s a need for the process to align with the community’s expectations for a more modern, continuous peer-feedback related process.
The UTG project replaced previous vocabulary maintenance processes (including harmonization) for HL7 internationally published normative standards. Additional information about project details, requirements, project management, and documentation can be accessed at the Unified Terminology Governance Project (UTG) Page
Maintenance of HL7 Terminology
This section provides a high-level overview of the workflow process for submitting a proposal and participating in consensus review.
- SUBMISSION: submit a proposal for changes that contain all technical details to the vocabulary
- VALIDATION: to ensure the proposal includes required information
- CONSENSUS REVIEW: voted on by the community
- PUBLISH: approved changes by a majority vote are implemented to the the current build of the terminology
The UTG process decreases the burden on HL7 resources by having the proposal submitter create and submit the content that they needed added, modified, or deleted in their own development branch (via BitBucket directly through Jira). Proposals are submitted using a Jira-based workflow that is open to the community. Automated checks and validations ensure that the content meets proposal requirements. The proposal goes through a consensus workflow to come to a resolution. If approved, the use of the Bitbucket branching allows simplified integration into the master repository.
The sections below provide a high-level overview of the Change Proposal Submission and Consensus Review Process.
Change Proposal Submission
The steps below describe the process for submitting a proposal. More detailed information on the process is documented at UTG Tooling and Proposal Documentation.
Don't know if you have permissions to be a Submitter of Vocabulary Change Proposals? When you create a proposal and it goes into the Environment Setup state, if you see a button on the top "Draft A Proposal" then you ARE a Submitter! If you don't see that button, you can become a Submitter by clicking this link (do not open in new tab):
The basic steps to submit a change proposal are:
Detailed step-by-step instructions can be found at: How To Submit a UTG Change Proposal
All change proposals are validated and formatted for a consensus review. Votes are weighted and there are several requirements (i.e. votes from specific users and groups) that must be met for the content to be approved or rejected.
HL7 members wishing to participate in the Consensus Review of proposed change proposals are welcome to participate. No tooling is required to participate.
The basic steps to become a proposal reviewer and participate in Consensus Review:
Detailed step-by-step instructions can be found at: Consensus Review and Voting Process
Setting Up Notifications for UTG Proposals
The UTG issue tracking system (JIRA) is set up so that reviewers must opt-in to subscribe to notifications.
The system has been initially configured for FIVE (5) different types of notifications or "filters":
Opting-in will trigger emails to be sent to you when any change proposal enters the subscribed "State" in the UTG workflow (the names above are the State names).
Here is a helpful Jira quickstart guide on using filters/subscriptions which can help you to better understand how to use this system in a way that works best for you personally:
Reporting a Vocabulary Issue
To report vocabulary issues found on the HL7 terminology pages, please follow the steps below. Note that reporting a vocabulary issue will add it to a queue of other reported issues in which content issues have been identified but no solution has been provided. Items in this queue will not be addressed as quickly as Change Proposals.
|ConfiForms Form Definition|
|ConfiForms Form Definition|