Talk: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.

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

Resolution

From approved motion at Sept., 2006 WGM and as presented and accepted at the Thursday round-table:

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)

Act.text can include information that is not in the other attributes/associations, but must include all information which is in such attributes or associations (with the exception of those identified above).

Act.text SHALL NOT be used for the sharing of computable information. Computable information must be conveyed using discrete attributes. Any information which Act.text contains not elsewhere exposed in encoded information will be opaque to computer systems. For this reason, Act.text should not be used to contain information which negates or significantly modifies the understanding of information encoded in discrete attributes.

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.

separating presentation from data

Within V3 we have been very good at making the meanings of each fragment of information clear, and in making the relationships between those fragments clear -- what we have been less good at is making the presentation of the information predictable.

For semantic interoperability you do not want the sender to be suprised by what the receivers clinical decision support system may infer from the data -- But just as important is that the sender should not be suprised by what the reciving system displayed to their users.

We need to provide far clearer definitions of what it is reasonable to expect. Many acts, certainly most clinical statements, will be displayed as either items in a list, as a summary in quarter to a tenth of the screen, or in a full screen "focus-of-attention" view. The first provides room for some text (?act.text? or maybe act.code.displayText or maybe act.code.originalText) and other information (subject, dates, author, location etc) mainly by context. The partial screen view and the full screen view gives scope for including more of the alternate text, as well as associations and context.

The fact that we cannot give clear guidelines on the use of act.text, means that we are far short of the requirement to provide predictable renderings.

GP2GP implementation guidence for the clinical statement "observation"

These are summarised as an example of the level of detail that is needed in an implementation guide or message specification to make use of act.text predictable

observation.text: The description of an act is a piece of free text or multimedia data that describes the observation in all necessary detail.

If present the text attribute should contain the full display text for the ObservationStatement constructed as follows with elements that are not present omitted:

1. uncertaintyCode.originalText (displayText if no originalText)
2. priorityCode.originalText (displayText if no originalText)
3. interpretationCode.originalText (displayText if no originalText)
4. subject.Relation.code.originalText (displayText if no originalText)

1. pertinentInformation[sequenceNumber= -1].Annotation.text
2. code.originalText (displayText if no originalText)
3. pertinentInformation[sequenceNumber= 0].Annotation.text
4. value (representation including all elements within value).
5. pertinentInformation[sequenceNumber= +1].Annotation.text

The order of some of the above elements may be varied. However the relative order of the elements in second list should not be changed.