Serialisation Annotations

This page includes a set of proposals for annotations for serialisation rules that can be used by the New ITS to support easier implementation of HL7v3 models. It is for discussion by MnM.

Serialization Model Annotation Rules from Canada (Lloyd)

The information needed to support the collapsing algorithm was the following:

• sort order (so that attributes and associations appeared in an order that grouped related concepts and was generally 'logical' to the reader
• "do not collapse" flag that indicates that the automatic collapsing rules should be ignored in some circumstances. (e.g. 1..1 association to Patient CMET should still be treated as a separate class.) Only used on associations and thus hidden behind the scenes, not visible in diagram.
• business names (to provide unique, meaningful names to the concepts, even when collapsed)

The diagram does not show explicitly what will collapse and what won't. The algorithm simply does the collapsing. The fundamental premise is that the only things shown in the collapsed view are those things that an implementer must make a choice as to what to populate. If an attribute has a fixed value, then there's no choice, and thus it doesn't show up in the collapsed view. If you have to walk 5 associations to get to an attribute, then there's no decision to be made by the implementer on how to get there and the associations collapse.

Serialization Model Annotation Rules from NHS UK

A set of annotations to RMIMs are proposed that describe some serialization rules. These are added in the form of textual RMIM "notes", that are saved into the MIF and can be interpreted by tools that come later in the message production process. (Ideally these serialization hints would be made in a fully graphical style, but this isn\’t achievable yet.)

Serialization rules available are

• Suppress a clone, RIM attribute or datatype attribute
• Rename a clone, RIM attribute or datatype attribute
• Collapse a clone into its parent

These operations can be local to the annotated clone, or can apply globally to the whole model.

An example annotation is : On a clone called ClinicalDocument: ITS:global.codeSystem.suppress;global.contextConductionInd=ccInd;ClinicalDocument=DischargeMessage

On a clone called recordTarget: ITS:recordTarget.collapse

The "ITS:" prefix indicates that this is special purpose comment. Semi-colons are used to separate multiple operations. The keywords "suppress" and "collapse" correspond to a request for that action on the attribute that comes before the dot eg recordTarget.collapse.

Model Annotation Syntax

This section advances a syntax for use as text comments on an RIM-based diagram. These are inserted by the user and picked up, via the MIF, by the Reshaping tool.

The annotations permitted are

• Suppress

attribute.suppress attribute.dataTypeAttribute.suppress eg code.codeSystem.suppress would remove the codeSystem datatype attribute from the annotated clone\’s code attribute. ("clone" being a diagram element derived from the RIM) .

• Rename

attribute=name clone=name eg. recordTarget=patient

• Collapse

clone.collapse eg global.codeSystem.suppress

The keyword "global" can also be used as a prefix, as in the example above, to make the change happen all over the model.

A BNF for the annotations is :

<rule> ::= "ITS:" <commandList>

<commandList> ::= <command> | <command> ";" <commandList>

<command> ::= <identifier> "." <action> | <identifier> "=" <name>

<action> ::= "suppress" | "collapse"

<identifier> ::= "global" "." <localIdentifier> | <localIdentifier>

<localIdentifier> ::= <RIMClone> | <RIMAttribute>

<RIMAttribute> ::= <RIMAttributeName> | <RIMAttributeName> "." <dataTypeAttribute>

Symbols undefined above :

<name> the new name for a renamed item

<RIMClone> the "clone name" of an RMIM shape, cloned from the RIM

<RIMAttributeName> the name of a RIM attribute of a clone eg. id, effectiveTime

<dataTypeAttribute> the name of a datatype attribute eg. extension, codeSystem

All white space is insignificant.

Example annotations

Note: In creating this ITS markup language, user readability was the primary aim. Ideally a fully graphical interface and presentation would be used instead of a textual one. This language was designed to suit the non technical user, hence the intuitive syntax of "=" to give an alternate name, and the english-like ";" to split multiple phrases. "Dot notation" eg patient.id is assumed to be widely enough recognised to be suitable for use.