VocMnt-Intro
Introduction
This document describes a formal, XML based language that can be used to create and maintain the HL7 Version 3 reference vocabulary. The immediate purpose of this language is to provide vocabulary facilitators a consistent and rigorous mechanism that can be used to specify HL7 vocabulary additions and updates. This mechanism will be supplemented with graphical maintenance tools that may partially or completely replace this language as the primary form of input. As this occurs, it is anticipated that the language specified here will evolve a form that will be used to record and transmit vocabulary changes between systems and tools.
This specification takes a different approach to vocabulary maintenance than that of its Excel-based predecessor. One of the major differences is that this language is procedural vs. table-driven. A vocabulary maintenance description consists of a sequential list of parameterized function calls such as RegisterCodeSystem, AddCodes, CreateValueSet, etc.
A second major difference between this approach and its predecessor is the underlying model. The Excel-based maintenance system blurred the distinction between value sets, concept codes and concept domains. The approach taken in this document is to separate the maintenance task into three separate parts:
- Code Systems – A code system contains a set of unique concept codes. Each concept code serves as a token to represent a useful category or class as viewed from a particular perspective. The definition and organization of the tokens within a code system represents assertions about the organization of the corresponding categories and classes within a real world. A code system may also carry information about the various ways that the categories or classes are identified in different situations and languages, as well as additional defining and identifying information that serves to clarify the intended meaning of the tokens
- Value Sets – A value set represents a list of concept codes. Value sets are used to specify a set of possible values for one or more RIM-derived coded attributes.
- Concept Domains (4) – A concept domain represents an abstract conceptual space that can be associated with RIM-derived coded attributes. A concept domain can be represented by one or more value sets, where each associated value set applies in a given context. Further, sub-sets of concept domains may, themselves, be represented as concept domains in a parent-child semantic hierarchy.
Each of the above parts is maintained separately, with the revisions to the code system(s) occurring first followed by changes to the value sets followed by any revisions to concept domain/value set associations that might be necessary.
Vocabulary Revisions Proposal
A vocabulary revision represents a related collection of updates to one or more code systems, value sets and/or concept domains. Each vocabulary revision comes from a single HL7 committee and is represented by one primary contact person. The vocabulary revision element has to be the outermost (first) element in any vocabulary submission.
A vocabularyRevision always begins with an editDescription element that describes the intent and purpose of the proposal. There are several textual elements in editDescription as shown below. The actual description should be recorded in the description element.
The attributes of the editDescription are listed below:
| creationDate | when the document was first created (format: yyyy-mm-dd). |
|---|---|
| proposalId | id should be unique within the committee submitting it. A committee id will be concatenated to get a "unique" id. |
| primaryContact | the name of the person responsible for the document |
| committee | the committee identifier primarily responsible for the changes |
| documentStatus | [Not exposed in application, and should be (1)] see table below: |
| Status | Meaning |
|---|---|
| Proposed | The document is in the initial stages |
| Submitted | The document has been submitted for review by the appropriate committees. |
| Reviewed | The document has been reviewed by the appropriate committees and is awaiting harmonization. |
| Harmonized | The document has been reviewed and voted on by the RIM Harmonization Committee |
| Final | The document has been recorded in the official RIM database and can undergo no further changes. |
| Rejected | The document was not accepted at some stage in the process. |
Table 1 - documentStatus values
The tools used to update the actual vocabulary tables won’t process Rejected status documents. In addition, warnings will be generated if Harmonized or Final documents contain Proposed ballotStatus action entries (described below).
Final and Harmonized submissions must also supply OID’s for all new code system registrations.
<?xml version="1.0" encoding="UTF-8"?>
<VocabularyRevision_._type xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="platform:/resource/HL7HarmonizationTooling/master/VocabularyRevision.xsd">
<editDescription committee="Modelling and Methodology" creationDate="2007-09-25" primaryContact="Woody Beeler" proposalID="Modelling and Methodology-The name of the game-2007-09-25.xml">
<proposalName>The name of the game</proposalName>
<description>do something</description>
<mainIssue>There SHOULD be an issue.</mainIssue>
<currentState>Chaos</currentState>
<optionsConsidered>Fratricide</optionsConsidered>
<rational>Peace should rule</rational>
</editDescription>
</VocabularyRevision_._type>
Figure 3 - Sample edit description
The sample above describes a new edit created on September 25, 2007 by Woody Beeler for the Methodology & Modeling committee. Note that the application will not process a proposal that has no content in the <description/> element of editDescription.
2.1 Edit Versions [Not exposed in application (1)]
A vocabulary revision may also include one or more edit version entries that track the history of the submission. Edit versions are optional and must immediately follow the editDescription entry.
Figure 4 - editVersion attributes -040
changeDate - date that the submission was changed
author - name of the person making the change
<editVersion changeDate="2003-05-12" author="Harold Solbrig">
<description>Enhanced examples</description>
</editVersion>
<editVersion changeDate="2003-05-19" author="Harold Solbrig">
<description>Adjustments for the revised template</description>
</editVersion>
Figure 5 - Sample editVersion(s) 2.2 Ballot Status[Not exposed in application (1)]
ballotStatus reflects the current status of the document in terms of the RIM Harmonization process. A ballotStatus can occur at multiple points throughout a vocabulary submission document, with the “innermost” status taking precedence. A ballotStatus has an optional note element that can be used to clarify the current state. ballotStatus has the following attributes:
Figure 6 - ballotStatus attributes-060
The first component of a registerCodeSystem entry is the ballot status of the action. The ballotStatus entry is optional. If it is omitted, it defaults to the innermost surrounding ballotStatus. If, for example, the ballotStatus for addCodesForCodeSystem is omitted, the surrounding registerCodeSystem or selectCodeSystem ballotStatus would apply. If there is no surrounding ballotStatus, the status defaults to “Proposed”.
action - the current status on this particular part of the submission as described by the table below.
vote - the actual vote (format: yy-nn-aa) where yy is the number of yes votes, nn the number of no votes and aa the number of abstentions. The vote attribute applies to Passed, PassedWithChanges and Withdrawn actions
Action
Meaning
Proposed
The proposed revision has been proposed (default).
Passed
The revision has passed RIM harmonization
PassedWithChanges
The revision has passed RIM harmonization subject to the changes outlined in the note.
Tabled
The revision has been set aside and will be reconsidered at a future time.
Withdrawn
The revision has been withdrawn, voted down or otherwise has not been accepted. It cannot be reconsidered in this context.
NonVotingItem
The revision consists of technical changes that do not need to be voted on.
Table 2 - ballotStatus action values
Tabled and Withdrawn entries will not be processed by the tools used to update the RIM vocabulary database. In addition, Proposed items will be considered in error when the vocabularyRevision.documentStatus is Final.
2.3 Revisions
A list of revision entries follows the edit description and edit versions (if any) . Revision entries are applied in the order that they occur. A revision entry can create or modify a code system, a value set or a concept domain. The following tags identify revision entities:
* codeSystemRevision - [Not fully exposed in application (2)] Register (create) a new code system or modify the contents of an existing code system. * valueSetRevision - Create a new value set or modify the contents of an existing value set. * vocabularyDomainRevision – Create or modify a concept domain.
The contents of these revision records are described in more detail in the following sections.
Revision records will be applied to the vocabulary database in sequential order. A typical sequence of revision records might consist of:
1) Register a new code system and define its contents
2) Create the value set (or sets) drawn from the code system
3) Create the concept domain and connect it to the value sets.
3 Code System Revisions [Not fully exposed in application (2)]
4 Value Set Revisions
5 Concept Domain (4) Revision [Not fully exposed in application (2)]
Appendix A – Beer Classification Example
The examples were drawn from a classification of beers. The source of these examples is provided in html in Appendix A. Appendix B – Beer Classification Example in XML
The XML source file necessary to create the full terminology of the Beer Classification is provided in XML form as Appendix B. Appendix C – Complete Listing of Examples Used in Document
A source file showing all of the examples included in this document is available in XML form as Appendix C. Appendix D – VocabularyRevision Schema Listing
The complete set of XML schemas that control these revisions is available as XSD files as Appendix D.
Nt1 Capability that is listed as Not exposed in application are functions that are not (as of this writing) supported by the Harmonization Tooling application.
Nt2 Capability that is kited as Not fully exposed in application represents a set of capabilities, some, but not all of which is implemented in the Harmonization Tooling application.
Nt3 Code System capability that is listed as Exposed under VS in application are functions that cannot be invoked directly, but that are present in processing value set changes on Value Sets whose Code System is established by a previous binding
Nt4 The term Concept Domain was formally adopted by the HL7 Vocabulary Technical Committee as the name for an abstract conceptual space that may be represented by (bound to) a set of concepts found in one or more specific code systems. Previous to this adoption, the preferred name for the same abstract conceptual space was Vocabulary Domain. In editing this document, the term "vocabulary domain" has been replaced with "concept domain", except where the term is part of the XML schema. In order to avoid "breaking" software tools that were built to the previous version of the schema, the XML attribute and element names retain the phrase "vocabularyDomain".
