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, February 28, 2013

Automatic Example Generation in CDA

One of the interesting discussions today on the HL7 Structured Documents call was about the requirement for examples inline in CDA implementation guides.  We finally agreed on the call to require examples inline for all new templates (and to permit elision if necessary to reduce the size in the guide).  With my implementer hat on, I'm very much in favor of including inline examples, and have strongly recommended and implemented that where I could in any guide I've ever worked on.  I like the inline examples to be focused on the properties of the document, section or entry that are constrained by the guide, and not on details of other templates that are included.  I do want a fully valid example (or two, or three ...) to be included with the guide, and that was previously agreed to by the workgroup.

One of the concerns expressed on the call was the difficulty in implementing example generation and validation in software (e.g., MDHT) to assist in implementation guide creation.  It is very challenging to figure out what should be generated and/or validated.

A few years back, I developed macros on the IHE Wiki that automatically generates examples from data used to develop CDA templates.  You can see examples of the output of those macros for Documents and for Sections on the IHE wiki.  I never did get around to developing macros for entries because those are a bit more complex (especially for the Wiki based macro language, which didn't have access to the CDA Schema or models).

The automated generation ensured that the document example included all required, recommended and optional sections, and that section examples included all required, recommended and optional subsections and entries.  For the same reasons that I didn't automate entries, I also did not automate examples for all the elements in the document or section.  Again, if I'd had access to the model, I would have done that for those though.

In creating inline examples where a template derives from and further constrains properties, I like the examples to highlight what is different from the derived template constraints (e.g., putting that part of the example in bold), as we did for Vital Signs Observation.

It may not be possible to completely develop example content within tools, but tools can certainly help.  And I don't think we should ever let the limitations of what can be automated prevent us from producing a high quality implementation guides with good examples.  I've personally hand-crafted more than 200 such examples, and I completely understand the tedious (and error-prone) nature of a non-automated process.  But the value of examples to implementers is such that they are a necessary part of any implementation guide, however they are created.

1 comment:

  1. Keith - Thanks for the post, I will look into the examples. The specific issue I was trying to address during the call and was not completely prepared to illustrate was that "abbreviated inlined examples" are an antiquated CDA Implementation guide artifact which are as you mentioned very error prone because their is a lack of validation and generation support for such example. The point I wanted to make was the Normative CDA IG should have not any examples and require a Non-Normative Developers CDA IG Companion guide which could be as robust as needed and have full examples of all templates, etc as needed.

    Currently within MDHT we support automated generation of all templates examples and customization for publication

    The generation code can be found here