This wiki has undergone a migration to Confluence found Here

Proposed Vocabulary Tooling Requirements

From HL7Wiki
Jump to navigation Jump to search


Health Level Seven Version 3 currently maintains several tools focused on terminology management and distribution. HL7 has agreed in principle to align its vocabulary tooling with the IHTSDO, to enable interoperability with HL7 tooling and the IHTSDO Workbench. This document sets out the proposed requirements for HL7 vocabulary tooling. It comprises a detailed description of what HL7 vocabulary tooling must, should and may deliver that will be used to:

  • Develop and maintain HL7's Version 3 vocabulary artifacts (Concept Domains, Code Systems, Value Sets)
  • Distribute HL7's vocabulary to internal and external users
  • Support review and analysis of HL7's vocabulary
  • Operate within HL7 Version 3 Harmonization and publication processes

Intended audience

The audience for this document includes HL7 Working Groups, project personnel, vocabulary facilitators and tooling implementers.


  • For the purpose of this document, the terms vocabulary and terminology are to be considered equivalent.
  • The HL7 Core Principles and Properties of V3 Models will govern the definition and operation of HL7 terms used in this requirements specification

HL7 Tooling Overview

A key piece in the development and deployment of the HL7 V3 Standard is the ability to bind structured vocabulary elements to HL7 V3 models. As such, HL7 has developed and maintains a robust structured vocabulary to facilitate the specialization or constraint of HL7 V3 models. The HL7 vocabulary - like all other structured vocabularies - requires a mechanism to facilitate efficient searching, validation and deployment its vocabulary

To this end, HL7 currently maintains several tools focused on the ability to search, maintain and publish its vocabulary. These tools are intended to support the terminology management and maintenance process defined by HL7 as the RIM and Vocabulary Harmonization processes. This combination of vocabulary maintenance processes along with supporting terminology maintenance tooling constitutes the solution to HL7’s terminology management solution. HL7’s current vocabulary tooling assets include:

  • Design Repository

The Design Repository (distributed as a rimRepos ZIP file under the Design Repository project in Gforge) holds the reference specification for the HL7 RIM and vocabulary. For the purpose of vocabulary, the Design Repository MIF (Model Interchange Format) representation serves as the source of truth for the HL7 vocabulary.

  • RoseTree

RoseTree is a Visual Basic application that provides a browser for the HL7 RIM and Vocabulary. RoseTree builds R-MIMs and HMDs from Visio designs and manages the repository storage of these artifacts, as well as generates XML extracts from the repository Publication Database (PubDb) for desktop and production publishing. RoseTree can process vocabulary content from either the MS Access or MIF representation formats from the Design Repository.

  • Vocabulary Maintenance Language (VML) Maintenance Tools

The VML vocabulary maintenance environment is a combination of a structured XML schema that defines the allowable operations that can be performed on the HL7 vocabulary, as well as a set of Java APIs that takes files conforming to the VML schema definitions as input, and updates a MS Access repository that serves as the HL7 Vocabulary repository. The final step is for the vocabulary content represented in the relational MS Access model to be exported into HL7’s Model Interchange Format (MIF).

It is necessary for VML users to hand develop the VML files that serve as input to the Java environment. This has resulted in limited uptake for VML within the Harmonization community.

The VML maintenance environment was developed at Mayo Clinic as a temporary solution to HL7’s vocabulary maintenance needs. It has been recognized within the HL7 community that the current vocabulary tools are inadequate to meet HL7’s growing vocabulary maintenance needs. Several efforts have been undertaken to try to improve the vocabulary tooling infrastructure within HL7, however, due to the varying use cases and requirements across different terminology users, a unified total solution has not been completed.

High Level Requirements

Business (Non-Functional) Requirements

Identifier Business Requirement Priority
VT.BR.001 HL7 users require access to the HL7 vocabulary to develop and validate HL7 models. HL7 vocabulary tools must be easily accessible and readily available to all HL7 members for use in developing HL7 standards that incorporate vocabulary.
VT.BR.002 The proper use of vocabulary is a fundamental aspect of HL7 V3. There must be education and training materials outlining how the HL7 vocabulary tools can be accessed, installed and used to develop HL7 standards that incorporate vocabulary.
VT.BR.003 Terminology content is rarely all inclusive or complete. HL7 vocabulary tools must provide the capability to create terminology content.
VT.BR.004 Terminologies can contains tens of thousands of concepts and terms. HL7 vocabulary tools must provide the capability to search terminology content.
VT.BR.005 The HL7 vocabulary requires consistent maintenance and update. HL7 vocabulary tools must provide the capability to maintain terminology content.
VT.BR.006 Terminology content needs to be moved to other systems and mediums. HL7 vocabulary tools must provide the capability to deploy (publish) terminology content to external sources.
VT.BR.007 HL7 has defined an interchange format for use within HL7 standards. HL7 vocabulary tools must interoperate with existing HL7 formats (MIF/MIF2) and publishing processes.
VT.BR.008 HL7 publishes its standards on its own internal schedule. The functional release schedules of the HL7 vocabulary tools must under the control of HL7.
VT.BR.009 HL7 has defined a formal review and maintenance process for maintaining the HL7 vocabulary content. HL7 vocabulary tools must be able to support terminology maintenance and development workflow processes.
VT.BR.010 HL7's vocabulary maintenance process is continually evolving. HL7 vocabulary tools must be adaptable to changes in HL7's terminology maintenance and development workflow processes.
VT.BR.011 Errors and inconsistencies often exist in terminologies. HL7 terminology tools must be able to perform terminology diagnostic tasks to identify errors, duplicates and other inconsistencies in the terminology.
VT.BR.012 Reviewing terminology content often requires comparison of terminology versions. HL7 terminology tools must be able to compare different versions of the same terminology at different levels of granularity (i.e. concept to concept).
VT.BR.012 The HL7 terminology includes terminologies that are created and maintained by external terminology agencies. HL7 terminology tools must be able to include terminology content from external terminology sources (i.e. SNOMED-CT, LOINC)
VT.BR.013 Terminology content is often required to be used by IT systems. The HL7 terminology tools should include the ability to be queried by a standard, Common Terminology Service.
VT.BR.014 Terminology developers often work collaboratively. HL7 terminology tools should include the capability for users to compare and/or share terminology edits during the terminology development process, perhaps over a shared Subversion service.
VT.BR.015 As an international SDO, HL7 members use varying hardware platforms. HL7 vocabulary tools should operate on varying operating systems (i.e. Apple, Microsoft, Linux)
VT.BR.016 It is often necessary to develop and maintain mappings between concepts from different terminologies. The HL7 terminology tool should facilitate the development, loading, maintenance and export of "map sets" that specify cross code system associations.
VT.BR.017 A key component of HL7 V3 terminology use is in the development, maintenance and sharing of value sets, or, subsets of terminology. The HL7 vocabulary tools should provide the ability to define, maintain, load and export value sets for use in HL7 as defined by HL7 Core Principles.
VT.BR.018 HL7 International requires [| open source] solutions to permit HL7 members the ability to participate in the evolution of HL7 tools.
VT.BR.019 A graphical user interface permitting terminology browsing, editing and development activities that is accessible and usable to casual users (e.g. vocabulary facilitators).
VT.BR.021 As an international organization, the terminology tools should provide a multilingual interface.
VT.BR.020 The solution must permit all HL7 members to participate in vocabulary maintenance processes in the evolution of the HL7 standards.
VT.BR.020 row X, cell Y
VT.BR.020 row X, cell Y

Functional Requirements

Identifier Functional Requirement Priority
VT.FR.001 Ability for a user to create terminology changes in their own workspace and promote appropriate content to the HL7 extension or the core.
VT.FR.002 Ability to identify core code system content from extension content made to the core visually.
VT.FR.003 Ability to support value sets composed from multiple terminologies.
VT.FR.004 Ability to load the HL7 terminology represented in HL7's Model Interchange Format (MIF).
VT.FR.005 Ability to export the HL7 terminology out of the terminology tool into HL7's Model Interchange Format (MIF).
VT.FR.006 The terminology tool should support backup and restoration to ensure rebuild and usability.
VT.FR.007 The terminology tool should provide the ability to browse terminology hierarchies based on the varying relationship types available to the terminology.
VT.FR.008 The terminology tool should provide the ability to create new relationship types for a specified terminology.
VT.FR.009 The terminology tool should provide the ability to create new property types for a specified terminology.
VT.FR.010 The terminology tool should provide the ability to create new qualifier types for a specified terminology.
VT.FR.011 The terminology tool should provide the ability to create new HL7 code systems
VT.FR.012 The terminology tool should provide the ability to create or modify new concepts within a code system (both HL7 and non-HL7).
VT.FR.013 The terminology tool should provide the ability to create or modify relationships between concepts in a code system.
VT.FR.014 The terminology tool should provide the ability to add or modify properties to a concept in a code system.
VT.FR.015 The terminology tool should provide the ability to add or modify metadata pertaining to a specified code system.