Skip to end of metadata
Go to start of metadata

Why is a document an Act?

Two short answers:

  1. We made a design decision in V3 early on that we would not model the real world directly but model what we observe or do that is of interest in the real world. Therefore we collect data about our observations, our prescribing etc etc i.e. we collect information about our activities or activities. Sometimes in healthcare, we collect the data about one or more acts and package that collection up into a document. Thus a document is simply a collection of acts and as such is an act in its own right.
  2. In the RIM, we have "red" classes, "yellow" classes "green", pink classes, cyan classes and cream classes. With the appropriate combinations of these classes you can say anything you like. Look at the definitions (not the names) and the attributes and choose the classes that fit the data you need to convey. The creation, use, and management of documents have, in principle, the same kinds of semantics as “red classes” (called “Acts” in the RIM) in terms of attributes, relationships to entities et al.

Note that this page does not cover the “are findings/conditions/concerns Acts” nor the “completeness of the RIM” discussion that some have raised as part of the discussion. Rene spronk 17:37, 6 Aug 2006 (CDT)

Electronic vs. Physical

There is no essential difference between electronic and physical. A book on a floppy disk or memory stick is no different than a paperback.

“I'm the author of this book" and "My son ripped pages from this book" has a completely different meaning of the word "book" even though both are nouns.

The RIM forces you to make a choice when you want to talk about either a physical thing or an electronic thing, and it's the same choice. You can talk about the physical medium of the book - dimensions, number of megabytes, font style, byte encoding, etc. Alternatively, you can talk about the information that the book contains. You use different classes depending which aspect you want to deal with.

One of the differences is that if I take the paper prescription and put it in the photo-copier and press copy 9 times, I will end up with 10 different entities. Each can have a different status, I can shred one, turn another into a paper airplane, us another to line the bottom of my bird cage, etc. However, there is only one Act. That's because only one order has been issued. Photocopying the piece of paper didn't change that fact in any way shape or form (however much patient Smith might like to pretend that it has when they take the photocopies to different pharmacies :>).

So please lets stop arguing about electronic vs. physical vs. forgeries vs. copies. That's not what this is about. This is about the physical medium vs. the conceptual content. HL7 lets you talk about either or both. We use different classes depending which aspect you're talking about.

The biggest mistake people make is to discount Act as an information structure and think you have to be an Entity to be "persistent". Act and Entity are categories distinguished by the real-world substrate of the information. It works pretty straight-forwardly.

In short, a "paper document" can be tracked as an entity in the RIM (as a ManufacturedMaterial Entity), however, all information structures are abstract human thoughts (i.e. Acts) not atoms or molecules. There was a lengthy discussion in M&M on this very topic back in the 1990's.

Long version of the first (short) answer

A slightly more formal way of answering the question: We can consider that documentation is a series of statements and statements are the actions of recording something.

The word "act" has many meanings: some are documents of decisions or actions (an act of parliament), some are some are verbs (to act). However, this is strictly irrelevant and attempts to argue that because HL7 called a class an "Act" it must for ever have the properties of a particular use of that word are pointless and circular.

The "Act" class in the HL7 RIM by its very nature (as a class in a static information model) is concerned with information. It represents information (whether knowledge or perception) about something that has happened or may happen in the future. As with any name or word you can worry about its formal definition - which is of course made up of words - or you can look to how it is used.

If we are referring to the physical thing on which a document is written then it is a physical entity. However, if we are expressing the information in a document then it consists of statements of things that happened, might happen, should happen or are believed to have happened. These statements involve unsurprisingly the things that participate as subjects or objects of those actions. Inevitably therefore the information model representation of the information in a document is not expresses simply as an entity or indeed as an Act but as a combination of all the classes in the information model (which in the case of HL7v3 means a documentation is represented by a combination of classes from the RIM).


Some think that was unfortunate in the RIM to use the term "document" instead of "documentation." Normally, the RIM naming convention was intended to use the nominal form of a verb, e.g. documentation for the infinitive "to document;" observation for the infinitive "to observe." However, that pattern was not always followed. Also, people do get sloppy in the narrative in the language used to describe the RIM. Almost all Acts can be read as activities that are 'performed': the Observation was performed, the Procedure was performed, the Supply was performed. But 'the Document was performed' doesn't make sense. What is intended though, is the act of Documentation. I'm not sure if it's proper English, but 'the Documentation was performed' sounds a lot better. It is this simple change that switches the perspective from entity-like to activity-like.

Note that one important reason why "documentation" was not chosen as the name of this class is because all Act event records in the RIM are documentations of real world activities. The Document act is for those conventional documents in the sense of having title, headed, sections, and free text. Naming this class "Documentation" would reinforce the very common misconception that only documents, not other Acts, can establish proper documentation, and that is of course not true. A better name that is still a nominalized verb might be "DocumentEdition" to make clear that it is the act of editing (and then releasing) a document. --Gschadow 19:40, 15 Aug 2006 (CDT)

Note [also] that no published healthcare information model models the "real world" directly, certainly not those models which would take a "document oriented" or a "health record structure oriented" perspective. These are in fact twice removed from the real world. Conversely, the RIM models the real world quite directly because real physical things and real people activity are both directly represented in the RIM. But, as this page explains, the essence of a document is not a physical thing. --Gschadow 19:32, 15 Aug 2006 (CDT)

(To see the discussion thread about this on the HL7 Listserv: "Why is document an act?" )

What schema version should be used for CDA R2?

Document Versioning could mean one of two things:

  1. Different versions of a clinical document in terms of content (e.g. a replacement document)
  2. Different versions of the structure of CDA documents within a single release.

Versioning of the structure of CDA documents

There is currently no version attribute which can be used to convey the infrastructure version (CMETs, datatypes, vocabulary) used by a document instance.


  • Schemaset 1 = CDA R2 schema from the Normative Edition 2005 (NE2005), with voc.xsd and datatypes schema from that same edition.
  • Schemaset 2 = CDA R2 schema from the Normative Edition 2005 (NE2006). This is the same R-MIM as in NE2005, using the same version of the XML ITS. with voc.xsd and datatypes schema from NE2006.

An instance that complies with schemaset 2 need not be compliant with schemaset 1 - for example if a new structural code has been added to voc.xsd or a data type has been extended with a new component.

For messages we have the following: Message(or Batch).versionCode: infrastructure versioning (CMETs, datatypes, vocabulary, transports) is communicated using the versionCode attribute and has values such as "2006NormativeEdition". The versionCode indicates "all infrastructure stuff that was normative as of the point and time the normative edition was released". For early adopters, it could be one of the development editions or an equivalent "packaged release" by a particular realm. See Interaction Versioning for details.

CDA doesn't have an explicit "Infrastructure Version". Possible solutions:

  • One is only allowed to use the NE2005 schema (the normative edition in which CDA R2 has been inititially published), until such a time that R3 becomes normative. There can then be no updates of voc.xsd or datatypes between releases.

    This is the current thinking of the strucdoc committee, although a formal motion hasn't been made.

    • This excludes a lot of enhancements (e.g. in the area of datatypes) one may want to adopt between R2 and R3. On the other hand adopting changes before the release of R3 leads to a requirement for versioning, and to backwards compatibility issues.
    • Note related to the number of versions/releases: after a couple of years it forces receivers to support a whole bunch of versions/releases for a single interaction/document.. which will certainly be true for CDA, documents are persistent and sometimes have to be stored (for legal reasons) for 110 years. This means that all those that process documents have to support a max of 110 infrastructure versions. This pleads for a mechanism that creates a minimal number of versions/releases.
    • This option seems to have been the intent of the committee, and is favoured by Bob Dolin.
  • Somehow support different/later versions of infrastructure (voc and datatypes) in one and the same CDA Relase
    • InfrastructureRoot.typeCode is used (mandatory) by CDA R2 documents to identify the MT that the instance corresponds with. If the MT artefact ID is properly versioned (in this case the MT versioning should include the infrastructure version in a precoordinated fashion) this can be used as well. v3 interactions don't have such a precoordinated versioning mechanism however, so it would be kludgy to do so for a document.
      • Alternatively, create a new CDA Release every time the underlying "infrastructure version" changes. Effectively this is the same solution.
    • Introduce a new attribute in ClinicalDocument.

What sections are contained in a document?

The CDA R2 (as a generic architecture) doesn't mandate the use of particular sections in a document, nor does it mandate the use of LOINC as a coding system for sections. (Section.code is CWE <= DocumentSectionType. This vocabulary doesn't have a predefined value set.)

If your implementation has to conform to a particular CDA implementation guide (one defined by another organization, e.g. the US-realm CCD guide), then that implementation guide could (and probably will) mandate the use of LOINC section codes, as well as a predefined hierarchy of allowable sections in a CDA instance.

If you're in the process of creating your own implementation guide for a specific clinical document type, then you could decide to use LOINC (it has plenty of section codes), and you can define your own section hierarchy.

CDA R2 using a non-XML ITS

  • In how far is CDA R2 "abstract"? - In other words: if one were to attempt to apply a different ITS (assuming there was one, e.g. ASN.1 or CORBA), what would the "open issues list" look like?

(CDA R2 Documentation) "Specific enhancements to the CDA Schema, above and beyond those defined in the HL7 V3 XML ITS, are described [..] in CDA XML Implementation (§ 6 )." Section 6 states: "The CDA Narrative Block, which is the XML content model of section.text, is manually crafted, as described above (see Section Narrative Block (§ 4.3.5 ))."

(Charlie McCay) The way that references between parts of the narrative block and the structured content are done in an XML specific way (reasonably enough because HL7 itself -as an standard- does not have an IIref mechanism agreed yet). This is the rationale for the schema edit: Add "ID" attribute, of type XML ID, to Section, ObservationMedia, RegionOfInterest

If one were to create a different ITS then the current CDA R2 XML schema or the manual tweaks made to them don't actually matter that much, as long as the tweaks didn't introduce new abstract concepts or constraints. One would start from the HMD (or in future: the MIF), additional work would be required (from an abstract point of view) in addition to the HMD to make it work:

  1. add the constraints as defined for Narrative Text (in an abstract fashion - strucDoc will hopefully create one at some point in time)
  2. deal with the IIRef issue in some way
  • No labels