Vocabulary Maintenance Language (Proposal)

Introduction

Proposal

Code System

Value Set

Domain

Properties

Appendices

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 proposal comes from a single HL7 committee and is represented by one primary contact person. The VocabularyRevision element has to be the outermost (first) element in any vocabulary submission.

Vocabulary Revision

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.

Description elements in editDescription

The attributes of the editDescription are listed below:

editDescription attributes

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] see table below:

documentStatus values

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.

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.

Example XML for editDescription

The sample above describes a new edit created on September 25, 2007 by Woody Beeler for the Methodology & Modeling committee.

NOTE: the application will not process a proposal that has no content in the <description/> element of editDescription.

Jump to top of page

Edit Versions

[Not exposed in application]

A vocabulary revision may also include one or more editVersion entries that track the history of the submission. editVersion is optional and must immediately follow the editDescription entry.

Attributes in editVersion

changeDate	date that the submission was changed
author	name of the person making the change

Example XML for editVersion

Jump to top of page

Ballot Status

[Not exposed in application]

ballotStatus reflects the current status of the document in terms of the RIM Harmonization process. A ballotStatus element 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:

Attributes in ballotStatus

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

ballotStatus action values

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.

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.

Jump to top of page

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] 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.

Jump to top of page