Definition of act.text

Issue

This is a discussion page - that will inform the harmonisation proposal that is being evolved at Fix definition of act.text

[from Rik Smithies] I'd like some further clarification on the use of act.text please.

I believe the rule for use of act.text is the following :

Relevant motion from the minutes of MnM Sep 05 WGM:

Motion

Act.text is a renderable/displayable version of the complete information which would reasonably be expected to be displayed to a human reader conveyed by the Act. The intent is that a user can read Act.text alone without seeing any of the encoded information and have no risk of misinterpretting or lacking full understanding of the full content of the Act. For example, II.root, or CD.codeSystem would not normally be displayed to a human and thus would not need to be exposed as part of Act.text.

Act.text represents the renderable/displayable version of the information of the "snapshot" of the Act exposed by that instance as communicated by Act.id[useCode='snapshot']. In the circumstance where no Act.id[useCode='snapshot'] is specified, the interpretation is that Act.text represents the snapshot as sent over the wire. To communicate historical versions of Act.text, an ActRelationship of RPLC must be used to point to the prior version of the Act with its own Act.text attribute.

The rendering is expected to include all 'descendant' ActRelationships and participations recursively navigating child Acts as exposed in that particular 'snapshot'. However, there are several data elements which are NOT expected to be included in the rendering. These are:

• Component Sections (ActRelationship=COMP, classCode <= DOCSECT)
• the title attribute
• anything attached to ActRelationship=XFRM)
• Previous versions (ActRelationship=RPLC)

The attributes and associations associated with the Act represent the encoding of some or all of this information. I.e. Additional information may be present in the content conveyed by Act.text that is not present in the encoded attributes and associations.

To communicate "supplemental text", an act relationship (e.g. "component" or "subject of") should be created to a separate Act with a bare Act.text attribute should be used to convey the supplemental information, possibly with a code indicating "annotation" or some similar concept.

Discussion

From this I infer the following :

- Act.text is considered a displayable superset of the information in the act, its attributes and associations

- Act.text can include information that is not in the other attributes/associations, but cannot exclusively consist of information that isn't in the other attributes and associations.

- In other words, it is not just another attribute that adds to the act as a whole, it is only a summary of the act as a whole.

- You cannot have data in the attributes and associations as a whole that is not contained in the act.text field, except when this data wouldn't be considered appropriate in a display version eg you may not wish to render Ids.

- Act.title (of any act) is an exception and will not be included in the scope of act.text.

- These rules apply to all acts except Component Sections (ActRelationship=COMP, classCode <= DOCSECT) and anything attached to ActRelationship=XFRM.

[from Lloyd McKenzie] While the above approach works nicely when representing a particular serialized instance, it tends to fall apart when using the RIM to represent an internal model constructed over time based on multiple instances. For example, if a prescription has "fulfilled by" relationships added, that changes the associations associated with the substance administration request, but obviously wouldn't change the Act.text.

It is correct to infer that the intention is that Act.text not generally be used for supplemental text except when sent as a component.

In terms of the consent model, a more accurate model might be to say that the consent is an instance of a consent definition, where the text of the definition reflects the "form". Alternatively, it could represent the complete filled in form, which would presumably address the subject, performer, etc.

[from Charlie McCay]

So the consensus definition (supported by the variations of actual usage) is "dragons lie here" and the definition and usage of act.text is (re)defined in the narrative of the model in which it is used.

This is disappointing -- if the motion is not acceptable then we MUST get an MnM consensus that will stick on this.

If that documentation lists 20 different ways that the attribute can be used, then so be it -- but the current definition does not help as it seems to be precise, but can be read in too many ways.

Action: A consensus needs to be reached on the uses of act.text, when this is reached all of the uses need to enumerated