HL7 Version 3: Substantive Change

Not Balloting this Cycle
HL7 V3 SUBSTANT, R1
HL7 Version 3: Substantive Change, Release 1
Last Ballot: Comment Only Ballot 2 - September 2007
Responsible Group Architecture Board Work Group
HL7
Chair of Architectural Review Board Mead Walker
dmead@comcast.net
Mead Walker Consulting
Editor Mead Walker
dmead@comcast.net
Mead Walker Consulting

View Revision MarksHide Revision Marks

Table of Contents

Preface
    i Notes to Readers
    ii Acknowledgements
    iii Changes from Previous Release
    iv Known Issues & Planned Changes
Purpose
Introduction
Substantive Change and the HL7 Balloting Process
The Importance of Substantive Change
Backwards Compatibility and Substantivity
Version 3 Specification Elements and Substantivity
    6.1 Storyboards
    6.2 Application Roles
    6.3 Trigger Events
    6.4 Domain Message Information Models
    6.5 Common Message Element Types
    6.6 Refined Message Information Models
    6.7 Hierarchical Message Descriptions and Message Types
    6.8 Interactions
    6.9 Examples
    6.10 Glossary Items
    6.11 Domain and Topic Overviews
Version 3 Foundation Documents and Substantivity
    7.1 Reference Information Model
    7.2 Refinement, Constraint and Localization
    7.3 Datatypes
    7.4 Vocabulary
Implementation Technology Specification Artifacts
Changes external to the ballot cycle
10 Errata
11 Glossary
Annexes
References
    A.1 HL7 Policies and Procedures
    A.2 HL7 Bylaws
    A.3 ANSI Procedures
Glossary for: Document subs

This document outlines rules and guidelines for determining whether a change to a Version 3 Specification is Substantive. Many Technical Committees (TCs) have asked for guidance on this matter. Many balloters have also asked for guidelines as to whether a change that they have requested would be Substantive.

The Architectural Review Board (ARB) has worked for some time to develop this document. The committee has decided to ballot this document for comments and looks forward to your feedback.

It is the ARB's intention to make this a Reference Document.

Many members of the HL7 community reviewed early drafts of this document and provided valuable feedback.

This version of the substantivity document is based on comments that were received when it was last balloted – September 2005. Based on ballot comments, we have made the following changes:

  • Removed the section that provided examples, and moved all examples into the sections dealing with specific aspects of V3.
  • Took a more rigorous approach to substantivity that treats changes to the tags used in balloted artifacts such as HMDs as substantive.
  • Added a section that discusses interversion compatibility and its relationship to substantivity.
  • Added a section on data types, and provided more detail on the treatment of data types.
  • Added a section on vocabulary.
  • Added a section on changes to Implementation Technical Specifications (ITS).

In addition, various typos were corrected and wording changes introduced.

The ARB would welcome any additional examples that you could provide.


The purpose of this document is to give guidance to Health Level Seven (HL7) Technical Committee (TC) Chairs in determining whether a change to a Version 3 Specification is Substantive. This document provides some general principles as well as specific rules and examples of what changes are substantive. It also provides some reference material on the role substantive change plays in the HL7 balloting process.

What is a substantive change? According to the American National Standards Institute (ANSI) a substantive change is one that directly and materially affects the use of the standard. The ANSI definition includes changes that would break solutions that were implemented using the specification as it existed before the change. It is important to note that, as an ANSI Standards Development Organization (SDO), HL7 SHALL be guided by the ANSI definition. Another way to express this concept is to note that substantive changes are those which modify the standard by adding or removing capabilities. In addition any change that changes the meaning of the message – whether by adding, subtracting or modifying content - is a substantive change. A change that materially affects the content of exchanged messages is substantive. For example, the addition of a new Trigger Event is substantive; adding attributes to an existing Message Type is Substantive. On the other hand, the correction of a typographical error, or the addition of an example message is not substantive.

When the ARB considers the matter of substantiveness, it generally uses the following test: a proposed change to the standard is treated as substantive if an interface would fail when a message is built, sent or received. This approach is similar to, but more expansive than, the definition of backwards compatibility However, a change that creates a backwards compatibility problem is substantive by definition.

When the ARB considers the matter of substantiveness, it generally uses the following test: a proposed change to the standard is treated as substantive if an interface would fail when a message is built, sent or received. This approach is similar to, but more expansive than, the definition of backwards compatibility. However, a change that creates a backwards compatibility problem is substantive by definition.

The goals of the HL7 balloting process are:

  • to meet its members' needs for specifications that are responsive to conditions. Timeliness is important.
  • to develop specifications that permit any interested HL7 member to participate and make their views known.
  • to encourage early implementation of specifications to ensure that final specifications are used and useful.
  • to publish high quality specifications that are accurate, clear, coherent, and consistent across the full set of specifications.

HL7 is governed by ANSI rules that are focused on ensuring that a consensus is achieved within the entire industry without any "special interests" skewing the results. Based on these rules, HL7's Bylaws and Policies and Procedures are intended to achieve these goals.

The definition of "substantive" change needs to be developed within this context.

The definition of "Substantive" change SHALL be interpreted within this context.

In a perfect world, every specification submitted for ballot would be complete, coherent, clearly expressed, consistent with all related specifications and delivered "just in time" for its intended use. Ballot reviewers would represent the full spectrum of affected parties and would vote in the affirmative, and the only comments would be small suggestions to add "polish" before publication. Additionally, many people would implement the specifications and actively provide feedback to continue to extend and enhance the specifications.

We realize that we do not live in a perfect world; each of us juggles many tasks, responsibilities and objectives. The tradeoffs are tough and it is the ARB's responsibility to provide guidance to the TCs so that the overall set of Version 3 specifications approaches this ideal. The ARB has been approached by TCs for guidance when they cannot clearly determine whether a change is "Substantive" or "Non-Substantive". The 2.x concept of substantive change is based on the premise that changes that would "break" solutions implemented using the specifications are Substantive. The ARB will apply this principle to Version 3.

Since the goal of Version 3 Standards is semantic interoperability, the overriding principle for determining substantivity will be whether a change modifies the content or meaning of the specification or if it impacts the validity of syntax. A primary Version 3 principle is the use of constraints as the delineation of correctness. The Version 3 specifications are model driven, so changes to any of the structural properties that would alter the constraints contained in the source models SHALL be Substantive.

Why is the distinction between substantive and non-substantive important? ANSI rules and HL7’s Bylaws require a vote on any substantive change. For example, if a substantive change is made to a document that was balloted at Committee Level 2, the substantive changes SHALL be balloted at Committee Level 3. The exception to this is that the Technical Chair must concur with a recommendation to initiate a subsequent Membership level ballot without re-balloting at the Committee level (See 15.07.03 of the HL7 Bylaws). The issue off substantive change is also discussed within HL7’s Policy and Procedures Manual.

The identification and designation of changes as Substantive or Non-Substantive plays an important role in the balloting process. When a TC creates a ballot package, the package SHALL include a list of all substantive changes from the previous version of the document. This list MAY also include additional changes. When a chapter or other section of a standard goes through successive ballots, this list SHOULD indicate changes from the prior ballot, not from the beginning of the balloting process.

It is important to distinguish between the distinct but related concepts of interversion compatibility and substantivity.

Substantivity is significant because of its role in the balloting process. Our rules for substantivity are based on the need to ensure that changes that are made to the standard are appropriately subjected to ballot review. For this reason, both additions and deletions from the standard are treated as substantive. As a general matter, any change which changes semantics is substantive.

  1. Interversion compatibility, on the other hand, is significant because as a way to recognize the significant cost of upgrading an installed interface from one version of the standard to a subsequent version. The rules governing interversion compatibility are centered around two notions: a) Old receivers receiving new messages should be able to continue receiving messages without error, b) New receivers should be able to understand old messages. In order to reduce this cost, HL7 V3 has introduced rules to limit the introduction of changes causing interversion compatibility problems. Those rules, which do not prevent the introduction of new features to the standard, specify that, before a feature can be removed, it must be listed as deprecated within an intervening Normative Edition of Version 3.
  2. As a practical matter, all changes that violate interversion compatibility rules are substantive. However, the converse is not true. Many changes which do not violate interversion compatibility may, nevertheless, be substantive.

This section lists the key elements of the Version 3 Specifications along with the applicable substantivity rules and examples. See the Version 3 Guide. in the HL7 Ballot document for more information on each element. As a general rule, changes that are made to non-normative elements are not substantive. Changes to normative elements MAY be substantive. (Note, as people move forward with Domain Analysis Models (DAMs) and other HL7 Development Framework (HDF) type changes, it is possible that this list will change.

It is also important to note that a balloter may comment on any portion of the ballot content. The committee is obliged to consider all comments. (HL7 Bylaws section 14.04.01).

Should the committee choose to respond to the comment by making changes to artifacts in the specification then only changes to normative artifacts may be considered substantive. Changes to non-normative artifacts are never substantive.

The following table summarizes the current set of ballot artifacts and indicates their status as normative or non-normative:

Reference Artifact Normative Status
1 Storyboard No
2 Application Role No
3 Trigger Event Yes
4 DMIM No
5 CMET Yes
6 RMIM Yes
7 HMD Yes
8 Message Type Yes
9 Interactions Yes
10 Example Instances No
11 Glossary No
12 Overview No
13 Domain Analysis Model No

Storyboards are not normative. Therefore, the addition of storyboards, deletion of storyboards, or changes to storyboards SHALL NOT be substantive.

Feature Substantive Comment
Identifier Yes Version number is allowed to change
Name No  
Descriptive Content No  

For more information on storyboards, see the Version 3 Guide section on Storyboard and Storyboard Narrative

Application roles are not presently normative. Therefore, the addition of application roles, deletion of application roles, or changes to application roles SHALL NOT be substantive.

Feature Substantive Comment
Identifier Yes Version number is allowed to change
Name No  
Descriptive Content No  

For more information on Application Roles, see the Version 3 Guide section on Application Roles

Trigger Events are normative. Therefore changes MAY be substantive. Such changes are substantive if they lead to creation of new trigger events, removal of trigger events, or substantial (what is this? A change that materially changes the meaning of the trigger.) change to existing triggers.

Feature Substantive Comment
Identifier Yes Version number is allowed to change
Name No  
Descriptive Content Yes If the change materially affects the semantics of the trigger event.

Here are some examples of Substantive Changes to Trigger Events:

  • Adding or deleting a Trigger Event SHALL be a Substantive Change.
  • Changing descriptive text that alters the reasonable interpretation of the functional meaning associated with a trigger event SHALL be a substantive change.

Here are some examples of Non-Substantive Changes to Trigger Events:

  • Correcting a typographical error in a Trigger Event description that does not alter Trigger Event rules is not Substantive
  • Adding or changing a V2 Reference to a Trigger Event description is not Substantive

For more information on Trigger Events, see the Version 3 Guide section on Trigger Events

Domain message information models (DMIMs) are not Normative. Therefore, changes to DMIMs SHALL NOT be Substantive. However, it is important that committees avoid making changes to the DMIM for a domain that removes structures used by RMIMs within that domain. If such a change were propagated into the RMIM, as indicated within the Version 3 Guide, it would be a substantive change.

For more information on Domain Message Information Models, see the Version 3 Guide section on DMIMs

Common Message Element Types (CMETs) are Normative. Changes to normative elements MAY be Substantive.

A CMET is a special kind of RMIM. The same rules that apply to RMIMs apply to CMETs. See below for further information.

For more information on Common Message Element Types, see the Version 3 Guide section on CMETs

Refined Message Information Models (RMIMs) are Normative. Changes to normative elements MAY be Substantive. As a general matter, any change to an RMIM that leads to the generation of materially different HMDs and message types is substantive. It is important to note that RMIMs are typically constructed using the HL7 Visio tools, and that the published HMDs and message types are generated algorithmically from the Visio representation of the RMIM. Therefore, if questions come up regarding a committee’s intentions for a RMIM, the Visio representation rather than accompanying description, SHOULD be taken as the authoritative representation of the model. Readers should note that CMETs and message wrappers are primarily defined through the construction of RMIMs; therefore these remarks apply to those models as well.

Feature Substantive Comment
Identifier Yes Version number is allowed to change
Name No  
Diagrammatic Layout No  
Class Presence Yes That is, the fact that a specific class has been used as a clone within the RMIM.
Class Name No  
Class Descriptive Text Yes  
Class Code/Type Code Fixed Value Yes  
CMET Reference Yes  
Attribute within Class Yes That is to say, whether or not a class from the RIM is included within a class instance within the RMIM.
Attribute Mandatory Flag Yes  
Attribute Multiplicity Yes  
Attribute Conformance Code Yes  
Data Type Assigned Yes The data type must be the one provided in the RIM or a legal restriction of it.
Concept Domain Assignment Yes  
Vocabulary Strength Yes  
Association for Class Yes  
Association Mandatory Flag Yes  
Association Multiplicity Yes  
Association Conformance Code Yes  
Constraint Yes A constraint may refer to a class, an attribute or group of attributes, an association or group of associations.

Here are some examples of Substantive Changes made to RMIMs:

  • Addition/deletion/change of an RMIM SHALL be a substantive change.
    Changes to an RMIM constitute addition, removal of a class clone, association to a class clone, attributes of a class clone.
  • The concept of adding and removing a class includes changes to CMET references which SHALL be substantive.
  • Changes to the characteristics of an attribute within an RMIM, SHALL be substantive. This includes changes to the name, assigned data type, the multiplicity of the attribute, and, if applicable, changes to the assigned default value or vocabulary domain.
  • Changes to the characteristics of an association within an RMIM SHALL be substantive. This includes changes to the role name, multiplicity, mandatory indicator, conformance code assigned to the association.
  • Changes to declared constraints on attributes or associations that materially affect the way that generated messages are created or interpreted when received.

Here are some examples of Non-Substantive Changes made to RMIMs:

  • Rearranging the graphical elements of the RMIM Diagram to make it easier to understand, without actually removing or adding a class clone, association to a class clone, attributes of a class clone
  • Adding notes to the RMIM that clarify but do not change meaning.
  • Changes to the RMIM narrative that clarify but do not change meaning.
  • When an RMIM is published with a reference to a CMET that is under proposal, but the CMET cannot be referred to within the Visio tool due to delays in updating V3 tooling, changes to correct the published version SHALL NOT be substantive.

For more information on Refined Message Information Models, see the Version 3 Guide section on RMIMs

Hierarchical Message Descriptions (HMDs) and Message Types are Normative. Changes to normative elements MAY be Substantive. Note, however, that according to current practice, all constraints applied to an HMD will be found within the RMIM it is generated from.

Feature Substantive Comment
Identifier Yes Version number is allowed to change
Name No  
Introductory Description Yes If the change materially affects the semantics of the HMD or message type
Element Ordering Yes Currently, variation here can only occur as a result of tooling changes
Name Yes These will not vary independently of the RMIM unless there are tooling changes.

Here are some examples of Substantive Changes to HMDs and Message Types:

  • Adding or Deleting Message Types is a Substantive Change.
  • Changes to declared constraints on attributes or associations that materially affect the way that generated messages are created or interpreted when received.
  • Changing the properties of an existing class, attribute or association. Any change made to an HMD or message type that would be substantive if that change were made to the originating RMIM SHALL be substantive. For example, adding a property to indicate that a set is unordered is a Substantive Change.
  • Changing the vocabulary domain assigned to an element within an HMD or message type SHALL be substantive.
  • Changing the labels used for classes or attributes SHALL be substantive, as long as these labels are used to generate tags, element names, or other component within at least one ITS balloted by HL7. As a result, changes to the V3 tooling used to generate schemas may be ballotable.

Here are some examples of Non-Substantive Changes to HMDs and Message Types:

  • Insertion of explanatory text that provides additional context for understanding a class, attribute, or association.

For more information on Hierarchical Message Descriptions (HMDs), see the Version 3 Guide section on HMDs

Interactions are Normative. Changes to Normative elements MAY be Substantive.

The same rules that apply to the components of an Interaction (i.e., Trigger Events, Message Types, etc.) apply to the Interaction. Therefore, a Substantive Change to a Message Type SHALL also be a Substantive Change to all Interactions that use the Message Type.

Feature Substantive Comment
Identifier Yes Version number is allowed to change
Name No  
Introductory Description Yes If the change materially affects the semantics of the HMD or message type
Trigger Event Reference Yes  
Transmission Wrapper Reference Yes  
Control Act Wrapper Reference Yes  
Message Type Reference Yes  

For more information on Interactions, see the Version 3 Guide section on Interactions

Examples are not normative. Therefore, changes to Examples are not Substantive.

Glossary items are referred too for each domain, however the actual glossary is kept as part of the V3 reference material, and is not substantive. Therefore, changes to glossary items, or additions or deletions to the list SHALL NOT be substantive.

Feature Substantive Comment
Name No  
Descriptive Content No  

The overview text that is provided sets the context for the models used to define HMDs and message types. However, they do not directly affect the content of message instances, and are not substantive. Therefore, changes to the overview text SHALL NOT be substantive.

The principals for determining whether changes to the V3 Foundation Documents are substantive or not are similar to those that apply within the domains containing messaging material. However, there are some differences.

The Reference Information Model (RIM) is subject to change through the harmonization process. The RIM has also been balloted by HL7 as a normative document. However, when the RIM is used as the source for V3 messaging specifications, HL7 allows source material form messages to include RIM contents that were added subsequent to a RIM ballot. Furthermore, HL7 has not defined uses for the RIM beyond its role as the source for the classes, attributes and associations used in V3 models and specifications. Therefore, when an HL7 RMIM, HMD, or message type is published within a V3 ballot, it SHALL not be a substantive change to link it to a more recent RIM version than the one used in a previous ballot. However, as noted above, if any new feature of the RIM is included in an HL7 RMIM, HMD, or message type, that SHALL be treated as a substantive change.

This section of the V3 ballot contains the procedures to be used by implementers when adapting and constraining the published content of the standard. Since change to this content does not affect HL7’s’ balloted content, but provides guidelines for how it should be used, it is not substantive.

Note, if normative specifications for defining conformance and certification were to be published in this section, it would be necessary to review the judgment offered above.

The characteristics of a data type are defined within the Data Types: Abstract section of the V3 ballot, and the description of the data types in that section constitutes their normative definition. Since changes to data types ripple through the entire standard, changes to data types tend to be substantive.

Here are some examples of substantive changes to data types:

  • Adding or removing a data type property.
  • Changes to a data type property that materially affects the way it is used.
  • Changes to the list of valid values (value set) that is used to support coded properties. For example, adding a value to the list of valid null flavors SHALL be substantive.
  • Changes to the rules that govern the way one data type can be substituted for another in the transition from RIM to RMIM, RMIM to HMD, or HMD to message type.

Here are some examples of non- substantive changes to data types:

  • Changes to the description of the data type or one of its properties that add explanatory power, without materially affecting its content.

The HL7 Vocabulary is subject to change through the harmonization process. However, the application of vocabulary to a normative HL7 product is itself Normative. Changes to Normative elements MAY be Substantive. The starting point for HL7 vocabulary consists of the definition of vocabulary domains, and the assignment of those domains to attributes within the RIM and the RMIMs. These assignments, as well as the definition of value sets used within the universal realm are substantive. Definitions of value sets within other realms are not substantive.

Here are some examples of substantive changes to vocabulary:

  • Removal of a vocabulary domain that has been assigned to an RMIM attribute.
  • Assignment of a vocabulary domain to a RMIM attribute.
  • Definition of a value set that is declared within the universal realm. This includes value sets assigned to attributes assigned a CS data type (the so called “RIM structural attributes”), and those assigned to data type properties.
  • The addition of codes to or removal of codes from a value set that is declared within the universal realm.

Here are some examples of non- substantive changes to vocabulary:

  • Changes to the description of a vocabulary domain that adds explanatory power, without materially affecting its content.
  • Changes to the description for a code description that adds explanatory power, without materially affecting its content.
  • Additions or subtractions to the set of codes assigned to a vocabulary domain that is not declared within the universal realm.
  • Removal of a vocabulary domain assigned to a RIM attribute, that is used in no RMIM.

For more information on the HL7 Vocabulary, see the Version 3 Guide section on Vocabulary

An Implementation Technology Specification (ITS) includes the rules that transform an HL7 messaging specification – an HMD – into a communications instance. The specific requirements that have to be addressed by V3 implementers are conditioned both by the ITS, and by the contents of the message specification being implemented. The contents of an ITS MAY be substantive.

Here are some examples of substantive changes to an ITS:

  • Changes to the principles by which the contents of an HMD are transformed into a message or other communication instance that changes an item used by the software processing the instance.
  • For the XML ITS, a change that leads to differences in element or attribute tags SHALL be substantive.

Here are some examples of non- substantive changes to an ITS:

  • Changes to explanatory text that do not change the meaning of an item used by software processing the instance.
  • For more information on a V3 ITS, see the Implemenation Technology Specification.

In some cases, committees or other HL7 bodies will detect perceived defects in the V3 standard between the time of balloting, and publication of the standard. It SHALL be acceptable, to make such changes if each individual change is clearly defined as non-substantive in terms of the discussion of the concepts of substantivity and non-substantivity provided elsewhere in this document.

 10Errata

From time to time, a defect will be found in a V3 standard document for which the recommended remedy requires a substantive change. If for some reason, it is not possible to ballot this change in a timely fashion, it is acceptable to document the remedy as an errata item to be published with the standard. If a proposed remedy to a defect is published as errata, the responsible Technical Committee SHALL include it as a ballot item for review by the HL7 membership as soon as possible.

NOTE that we have just figured out how to add terms from foundation documents to the main v3 Glossary, and will do so with these terms soon.

The HL7 Ballot Process is detailed in the HL7 Policies and Procedures Manual in Articles 14 and 15.

A.2   HL7 Bylaws

The HL7 Ballot Process is also discussed in the HL7 Bylaws in Articles 14 and 15.

B.1 
Backwards Compatibility
A change that would create a backward compatibility problem is a Substantive Change. For backwards compatibility, a message recipient is expected to process a new message and ignore added material. If there is new material that needs to be parsed in order to process the message given its new definition, the change SHALL be Substantive.

Some general rules for a Backwards Compatibility are:

  • From the V3 perspective, the focus is on message types. As long as there is a set of message types that do what was done before, the contents of a version are compatible with those of the previous version are backwards compatible.
  • Neither attributes nor associations can be removed from a message type.
  • Association cardinality cannot be tightened.
  • You can change attribute conformance from Mandatory to Required, and from Required to Optional, but not the reverse. Tightening attribute conformance from Optional to Required, for instance, will break backwards compatibility and will cause legacy messages without those formally optional attributes to fail.
  • You cannot remove values from the HL7 defined value sets for structural codes. This includes all attributes with CS datatypes.
  • If a particular coding system is referenced, it SHALL NOT be removed.
  • If a particular value set is associated with a domain within a ballot, the value set reference SHALL NOT be removed, nor may any code be removed from the value set.
  • No interaction may be removed that existed in a prior ballot. This precludes removal or redefinition of a trigger event.
  • Receiver responsibilities may not be removed from interactions.

B.2 
Non Substantive
The ARB considers a change to be Non-Substantive if it would not cause an interface to fail when a message was built, sent or received. Changes made to non-Normative material SHALL NOT be Substantive. Non-Substantive changes do not change the meaning of the standard.

B.3 
Substantive
Substantive changes modify the standard by adding or removing capabilities. The ARB considers a change to be Substantive if it would cause an interface to fail when a message was built, sent or received. This is similar to, but more expansive than, the definition of backwards compatibility. A change that creates a backwards compatibility problem is Substantive by definition.

The ANSI Definition of substantive change is:

A substantive change in a proposed American National Standard is one that directly and materially affects the use of the standard. Examples of substantive changes are below:

  • SHALL” to “SHOULD” or “SHOULD” to “SHALL”;
  • Addition, deletion or revision of requirements, regardless of the number of the changes.
  • Addition of mandatory compliance with referenced standards

View Revision MarksHide Revision Marks Return to top of page