Convert your FHIR JSON -> XML and back here. The CDA Book is sometimes listed for Kindle here and it is also SHIPPING from Amazon! See here for Errata.

Thursday, June 18, 2015

HL7 Template Versioning Rears its ugly head ... again

One of the challenges we've discovered in the C-CDA 2.1 DSTU Update project is the process needed to update templates that reference updated templates.  This involves what we've grown to know as the "ripple effect".  A change to one template, such as the Result Observation requires new versions of templates all the way up the chain, resulting in changes being required to 13 other templates.  Each of these changes requires six additional steps according to a list provided by Brett Marquard, my co-lead on this project:
  1. Update the Title
  2. Update the Identifier
  3. Update the conformance binding to the new template extension
  4. Re-add the figure and update since versioning does not carry forward
  5. Update the contained entity
  6. Update the containing entity
  7. (my addition to the list) Update the examples!
I had proposed today on the SDWG call that we consider that version specific references to a template are really an errata.  The point of changing to the new versioning strategy was to allow a version non-specific reference to be made to a contained template in a conformance constraint.

A contained template reference can be rewritten from:

Results Section (entries optional) (V2) (optional)1. SHALL contain exactly one [1..1] Result Organizer (identifier: urn:oid:2.16.840.1.113883. (CONF:15516).
to the following:
Results Section (entries optional) (V2) (optional)1. SHALL contain exactly one [1..1] Result Organizer (identifier: urn:oid:2.16.840.1.113883. or later revision) (CONF:15516).
Pros for this proposal:
It eliminates the necessity to ripple. Because this would be deemed errata, this change DOES not require a change to anything using Results Section, and Results Section can use a later version in other guides calling on it.

Note: The guide itself can have a conformance constraint that indicates that all referenced templates must conform at least to the versions of the referenced templates present in the guide.  This turns into a single Schematron constraint that might be complex, but can certainly be developed easily from a list of template identifiers present in the guide.

Cons raised on the call:

  1. The specificity of the guide is reduced.
  2. The tooling would need to be changed to support this.
  3. There are concerns that this means all versions of a template would need to be backwards compatible in the future.

While I agree that this reduces the specificity of the guide, the present degree of specificity is what causes this ripple effect, and this is, as one person put it: "... a bad bad problem ...".

With regard to the tooling, yes, we would need to address it in the tooling at some point.  However, we could automatically correct the output of the tooling by making a list of the necessary template OIDs that would require this change, and automatically address making the changes in the Word Document.  Later changes would be needed to address the binding change, but those could be made after the publication.  This is, of course, not ideal, but better perhaps than further delays.

Finally, with regard to backwards compatibility, I would argue that if there are major changes to the way a template is modeled (such as was done for problem and allergy status), the appropriate way to handle those changes is to DEPRECATE the old template, and create a new one if need be (we didn't need to do that for those templates, because we handled it differently).

Yes, this would ALSO require some changes to the automatically produced Schematron in the tooling, but I can automate many of those changes as well.  I would also note that tooling issues, while important, should be secondary if a viable workaround exists.  I'm getting really discouraged about how proprietary HL7 tooling are preventing standards work from progressing the way it needs to.  If this were Open Source, at least I could work on fixing the tooling issues.

The HL7 Templates DSTU recognizes containment of another template as one of the possible kinds of constraints on a template (See section 2.10.2).  It also recognized static or dynamic bindings associated with the containment constraint (see section 2.10.5):
... an artifact is bound to an element either as
  • STATIC, meaning that they are bound to a specified version (date) of the artifact,
  • or DYNAMIC, meaning that they are bound to the most current version of the artifact. 
Value set bindings adhere to HL7 Vocabulary Working Group best practices.
A STATIC binding is a fixed binding at design time whereas a DYNAMIC binding implies a need for a look-up of the (most recent) artifact at runtime.
It can also be found in practice to “freeze” any binding defined as “dynamic” to the most recent artifact at the time of the official publication, making “dynamic” bindings actually “static” for the most recent version. This makes the publication stable with regards to the binding of artifacts.
I'm proposing this as ONE possible solution to the ripple effect.

Another possible solution is to be able to automate making some of the changes to the templates. When we originally made these version number changes, I worked with Lantana to make the changes using an XSLT on a download of the templates in the guide (including fixing examples), and then the material was re-imported into the guide.  I could do this again. 


  1. Keith,
    Interesting that you cite value set binding in this because I believe we do need to make more clear the expected meaning of DYNAMIC is "from this date forward, any valid "version" is acceptable." With that, we still need a way to then say "Using that model, I then want to use a specific version for a particular use." We essentially do this now without a concrete specific artifact, when CMS posts an eCQM release that specifies specific value sets to be used with eCQMs defined by HQMF that all have DYNAMIC bindings. Note that in these situations implementers are being given specific guidance to NOT use the "current" value set expansions but instead those specified in the release documentation. We are just beginning to discuss if some artifact - a release parameter profile - could be crafted that captures the additional parameters needed to specify the specific value set versions to be used in that situation.

    1. Rob, Vocabulary bindings always confused me. I included that material ONLY because eliding that one sentence didn't really make the quote all that smaller, and eliding it would have been more confusing than leaving it in. However, I do see parallels between versioned vocabulary binding and versioned template binding.