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.

Wednesday, May 29, 2013


Before I go any further with this post, let me say loudly that:
I agree, we [the HIT community] need more CDA examples to work with!

One of the discussion topics over on the Structured Documents list this week is about the need for more examples of the Consolidated CDA specification.  Two arguments being promoted are: The documentation isn't good enough to stand on its own without MORE examples, and that implementers don't read the specifications.  Oh, how true that last statement is in Healthcare IT. And how wrong it is as well.  Someone explained that "I do not expect them to look at 3000 pages of manuals on 7 different web sites..."

I have so little patience with that attitude.  Let's take a standard like XML.  I have four books on my bookshelf about XML in general, including this one that I reviewed not too long ago.  I have two books that cover XML Schema.  I have two books covering XSLT.  I have two books about Java and XML.  I have one about Java and SOAP.  I have all the W3C XML standards printed and bound.  I have links to my favorite web-sites on XML, which include at the top, the W3C and w3cschools, and also mulberrytech, and

My collection of material on XML runs to more like 30,000 pages, rather than 3000.  And I know XML developers who have more. I'm what I call an HTML duffer.  I write HTML pages (and have done so professionally for quite some time), but I'm not an expert at HTML.  I only have about 10,000 pages or so of content on HTML in my library.  I'm NOT extraordinary by the way.  I know HTML duffers whose book collection exceeds my own, and experts whose collection exceeds it by an order of magnitude.

I EXPECT all engineers who need to use a specification to do their best to use it correctly.  I expect decent engineers to do more than look at one example.  I expect GOOD engineers to read the specifications and use them.  I expect GREAT engineers to read the specifications, comment on them, fix them, and read as much as they can about them.

Don't tell me proudly that you've never read a specification.  It's NOT a badge of honor.  Yeah, OK, you've come to an outstanding understanding of the technology without reading the specification.  Great, how to you have a meaningful discussion with someone who's actually read it, or even better, created it. If you haven't read it, you've lost the opportunity to develop common ground.

Yes, we need better specifications, and we need shorter specifications, and we need easier to read specifications.  And we need a lot more examples.

But we also need professional engineers who will live up to the job title.  Not just weekend warriors who want to be able to show off what they did in their spare time.  Healthcare is simply too important for that attitude.



  1. Keith,

    Great standards are used by folks with all levels of expertise. Neither HTML nor XML would be what they are today if the table stakes for any project in any context was your bookshelf.

    Even when you apply an "engineer" filter it's still not one size fits all. Engineering is about working within constraints - the best engineer is the one who gets the best results across all constraints (economic, operational, fit for purpose, safety, etc.) - not the one who knows the most in a conversation or is the most well read.

    I've only got a masters degree in computer science and a track record of successfully managing large engineering product organizations of several hundred folks - so not sure I qualify under you definition of "engineer". I'm proud of the total results of my engineering activities and would not be prouder if i had allocated more time to reading specs than was necessary for what I needed to do.

    Of course if I was tasked with creating specs or influencing them that would be a different story. But using them? No badge of honor in my book for size of bookshelf or scores on a certification exam - just for results...

    Mostly, I'm proud of the people who wrote the specs (and the tools and educational material layered above them) in a way that allowed them to be used so successfully by myself and others - including many who don't even know there is a spec. My kids have done some great things with HTML that made our world a better place, and they don't even know what a spec is.

    We need weekend warriors, and folks who can be successful with CDA-based IT projects that only have a couple days allocated to them. And we need experts like yourself who pride themselves (rightly so) on their mastery of the underlying models and concepts.

    Right now, though, I think we need to be a lot more focused on making the folks who won't read the specs successful - or all the time spent by those who not only ready them but also wrote them, will be time spent on a failed engineering effort.

    1. I have neither a master's degree (nor even a bachelor's degree), nor can I claim to have managed organizations that large. Surely if I qualify, you qualify as well.

      In finding people to work on projects, I look for the smart people who are willing to learn from others, and who take the trouble to use the available information to produce results. One source of evidence of that for me is on the engineer's bookshelf.

      When you get to the level of having to understand the XML of CDA, you've gone beyond the weekend warrior project, or the two day spreadsheet. You better be using some of the Open Source that already does it right, and which was built by people who took the time to understand the specs.

      If what you are doing is for direct patient care, and as an IT specialist in the hospital, you cannot be given more than two days to do it, and cannot be bothered to read the specifications ... well, needless to say, I hope I never wind up needing treatment there.

  2. It's a fact of life that many of those who use standards wont read the specifications for the standards. The burden is on the standards to present themselves in different ways in order to be accessible to as many as possible. A 2 page crash-course on XML alongside a 3000 page specification is better than just a 3000 page specification by itself.

    1. I'm not sure how your advice helps.

      I agree that standards should present the materials in many different ways in order to be accessible. In fact, Consolidated CDA presents the specifications in tabular, diagramatic, example, and detailed conformance statement format (as recommended by the S&I Framework Documentation workgroup, which I cochaired).

      But even with all those various forms of content, if the engineers NEVER read it, who benefits? Certainly it would seem to be a waste of time for the engineers who don't read the specifications.

      Oh, and you'll find a 10-page crash course in chapter four.

  3. Keith,

    Thanks for the words. I haven't done as much of this reading as I ought to (perhaps because I rely on computer screens more than on books, and computer screens are notoriously hard to read from). Thanks for the suggested links, and the reminder to spend more of my (so-called) down time reading the formal descriptions of the systems and languages I'm supposed to know all about.


  4. Keith,

    I think your right to some degree on the RTFM part of C-CDA or just CDA, but knowing the standards myself they kind of make me ill. CDA seems to have been created to try and solve all of the problems with health IT at once and that type of thing never works out very well. Couple that with the fact that CDA based specs tend to have semantic meaning embedded in them and declared in word documents and are a number of times are further constraints on existing CDA based specification that then introduce consistencies in the templates and the whole thing becomes a mess.

    Then you get to the point where you're not suppose to use the template ids for anything other than validation , even though that semantic meaning is buried in the word document. And then for validation dont get me started on the actual validity of the HL7 schematron rules :(

    My personal opinion is that all CDA based specifications are a mess because the CDA is a mess. Generalization is the root of all evil and CDA is the king of over generalization along with being the queen the under specification of required elements/attributes; just about every data element in CDA is optional.

    Then I hear of green cda and think maybe it would be a good thing, provide a simplified easy to understand data model that could just be transformed back to CDA and vice versa. But then I come to find out all it does it make things worse by providing a junk drawer namespace without any actual mappings on top of it. It's the wild west where every body can do their own thing , toss it under the green cda namespace and your good.

    A good amount of this probably boils down to the fact I dont see too many people on some of the HL7 committees like the structured documents working group that actually have to implement any of this. Or actually could for that matter, there are an awful lot of non technical people in those groups making technical decisions. And just because some of them are co-owners of a HIT consulting company does not mean they can code, or actually understand things at an implementation level.

    So I understand the RTFM part of things, but I have and it does not make it any better because all of the underling issue with why it's not a very good spec are still present.

    1. I think that is suppose to be "introduce inconsistencies in the templates"