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.