RIM ITS Specification

Ballot Notes

This should not be taken as evidence that it will supplant or replace the use of the XML ITS. Such decisions may be considered in the future when there has been some practical experience with this new ITS, as well as other alternative approaches to ITS and RIM-related data transfer.

It's still not clear exactly when the RIM will switch from data types R1 to data types R2. Verions "x" will be fixed when this is known.

Scope

This specification describes a RIM based serialisation expressed in XML. The names and types found in the XML instances and the matching schemas are taken directly from the RIM. This RIM serialisation is suitable for use where ever RIM based data is transferred. As a consequence, this serialization may be considered for use wherever the RIM is an appropriate model for expression of the data. These circumstances include

• HL7 v3 messaging between trading partners on an agreed basis
• SDA documents, potentially including future versions of CDA
• ad-hoc transfer of RIM object graphs in Rim-Based Application Architecture contexts.

Comparison with the XML ITS

HL7 has also defined an XML serialization of v3 message models called the HL7v3 XML ITS. The XML ITS uses the names and types from the static information models (which are based on the RIM), instead of those from the RIM. The data is largely the same, though any values that are fixed or defaulted in the static model may be omitted from the instance. The XML ITS produces a different schema for each model, which is considered a real disadvantage by some implementers, who find it difficult to re-use their implementations when same data is represented with multiple schemas. The XML ITS does have the relative advantage that it offers considerable additional potential for schema based validation, but this has not been fully realised as the schemas have no formal status; do not correctly describe the instance in all respects; and cannot perform a complete validation.

The RIM ITS is a normative specification to ensure that users that commit to it can rely on its future.

Design Principles

The RIM is defined as a class model, and can be expressed in UML. The fundamental design principle is that the RIM serialisation format should be based on the standard industry approach to serialising UML class diagrams in XML. Accordingly, the following rules are followed:

• Each UML class attribute is an element.
  • The name of the element is the name of the attribute.
  • The type of the attribute is the type of the attribute (but see not below about data types)
• Each UML association is an element
  • The name of the element is the name of the association
  • The type of the element is the type of the RIM class at the other end of the association
  • Where the association has cardinality > 1, the element repeats.
• Where the type of the element is different to that expected in the design (i.e. polymorphism) the type is indicated by the use of xsi:type

Note that because of some design and implementation issues discussed below, the actual serialization format is different to that created by a direct transform from the RIM, but the schema may be reverse engineered to a UML model very close to the RIM, and with identical semantics.

Implementation Choices

References

In the simplest case, the RIM graphs that are being transferred are Directed Acyclic Graphs which map directly to an XML document. However there is no reason that valid RIM graphs should not contain cyclic references; in fact, this would be quite normal.

When an object graph contains cyclic references, some method must be used to resolve this. This specification uses id/idref to refer from one object to another: when an element has an idref attribute, the logical rim object is the one represented by an xml element with a matching id attribute.

Some rules about references:

• An idref attribute SHALL have a matching identified element within the scope of the same xml document
• idref attributes can be forward - the element may be encountered later in the document
• Because a schema that supports id/idref use must make all attributes and elements optional, there are two variations of the RIM schema, with and without id/idref support. References may be avoided by trading partner agreement, but unless explicitly stated, references are allowed. Other than this, the two schemas describe the same set of instances

Note that context conduction is a feature of the RIM, and therefore must be represented in a RIM ITS (as also in the XML ITS). The interaction between references and Context Conduction is at present undefined. (NOTE: Referred to MnM as a hot topic: Context Conduction in cyclic RIM graphs)

Data Types R1 or R2

As of RIM version X, the RIM uses data types R2. Accordingly, the RIM ITS for versions from X use data types R2 and the ISO data types. For RIM versions prior to X, the RIM ITS uses data types R1.

Note that since R2 is backwards compatible with R1, it is possible to use R2 in the place of R1 for RIM versions prior to R1. This can be done by trading partner agreement, and requires some data type name mapping (see Appendix 1). Note that it is also possible to use data types R1.1 by trading partner agreement with the RIM ITS.

Description of the format

Wrapping Element

The root element of all RIM ITS instances is an element named "rim-graph" in the namespace "urn:hl7-org:v3-rim". This element introduces the fact that the instance contains a RIM object graph, and carries some control information. The element is usually the root element of the XML document, but this is not required. The element has the following attributes:

model	Optional	The static model that the RIM graph conforms to. It is not necessary for the RIM graph to conform to any static model, nor is it required to populate this value. However populating the value may help some instance processors, so it is recommended that this be populated where possible
version	Mandatory	The version of the RIM upon which this serialization is based. See note below concerning RIM versions.

In addition to these attributes, the element has a mandatory child element "Content" which has a type of "InfrastructureRoot" and contains the actual RIM object graph.

• • • (Question: is there any utility in exchanging a null object graph?).

Clone Names

Transforming from the XML ITS instance to the equivalent RIM ITS is a trivial process. The reverse transform is not trivial. The RIM Object graph must be speculatively matched against the constraints specified in the XML ITS expressed model using a depth first matching algorithm. In addition, terminology subsumption support is often needed. Though this process is not overly complicated, it is certainly relatively CPU intensive.

Some recipients may need to transform from the RIM ITS to the XML ITS, either literally or logically. To save these recipients from performing the depth first matching test, the sender can put the clone name from the expressed model in the attribute "cloneName" which is defined as an additional property of infrastructure root for the purposes of this serialization.

The cloneName attribute is optional, though may be required by a trading partner agreement.

Whitespace

There is no element text content in the RIM ITS. Whitespace should be ignored except inside some data types (ED and/or ST depending on data types version).

Character Encoding

Any valid XML character encoding may be used. The character encoding SHALL be explicitly declared in the instance.

• • • (err, must it be? It seems like good practice, and it's hardly onerous)
    • Comment from Charlie: I suggest that the criteria for this sort of decision should be explicit:
      • How many commonly used XML processing frameworks do not produce an encoding attribute?
      • How many cannot be configured to produce one?
      • What are the risks associated with supporting the default guesswork?
      • Do we have evidence that allowing the attribute to be left out does cause problems?
    • My concern is that where we introduce a new constraint on the underlying XML specification, we need to be clear that there is a good reason for doing so. From this discussion I can see why the underlying W3C specification could/should be tightened up in some future version - but am not clear that the HL7 profile of it should be.
    • Also - we need to be clear what the conformance implications of strong recommendations are. In particular, if we "strongly recommend" something, what is the impact on systems and project-specific specifications? Either the recommendation needs to be converted locally into a "MUST" or receivers must be able to work appropriately were there is no encoding attribute. Whoever makes the decision whether to follow the strong recommendation, would need an explicit rationale for the recommendation, in order to assess the balance of risk/cost in the local context.

xml attributes

The following table describes the usage of attributes defined in underlying xml specifications:

xml:lang	SHALL not be used
xml:id and xml:idref	Used to indicate object references.
xsi:schemalocation	SHALL not be used, and SHALL be ignored if encountered.
xsi:type	MAY be used anywhere, SHALL be used when the type of the instance is not the same as that declared in the instance (in which cases, type used SHALL be derived from the type declared)

Rim Graph Entry Point

Any RIM object may be represented in the content element, including Participation and ActRelationship. However these two classes SHOULD not be used, as doing so does not make a lot of sense in RIM methodology.

RIM Versions

New versions of the RIM are released on a regular basis. The following relevant changes may be expected with a new version of the RIM:

• Addition of new attributes
• Addition of new associations
• Changing the type of existing attributes
• Deprecating existing elements

Ongoing releases of the RIM are usually backwards compatible with regard to the RIM ITS; even when element types are changed, they are usually backwards compatible. However this is not guaranteed, and it is possible that future changes to the RIM will cause non-backwards compatible changes to the xml format specified herein, and to the schemas. Such changes will not cause a change to the namespaces used by this specification. Implementers will need to formulate their own policy, perhaps aided by trading partner agreements, to manage this issue.

The version attribute in the root rim-graph element SHALL be populated to assist readers of the instance to manage this issue.

The schemas make this a required element, and document the version of the RIM they are derived from as the default value for this attribute, but they do not fix the value to the current version, so they may be used with older versions of the RIM where possible.

Conformance

Note: some of these rules are documented elsewhere in this specification

1. The XML instance SHALL be valid with respect to the schemas specified herein. Note that applications are not required to enforce this, nor to reject known non-conformant instances

• • • This means that the R1 instances cannot carry a few otherwise valid sorts of data

1. The XML instance SHALL commence with a single element called "rim-graph" in the namespace "urn:hl7-org:v3-rim".
2. The rim-graph element SHALL have a version attribute documenting the version of the RIM upon which it is based.
3. The rim-graph element MAY have a model attribute specifying the model to which the data conforms.
4. The rim-graph element SHALL have a single child element called "content" in the same namespace as the rim-graph element.
5. The content element and it's contained content SHALL be valid according to the RIM specification.
6. Elements representing RIM objects MAY have a cloneName attribute specifying the clone to which they conform in the specified model.
7. Elements SHALL not have a cloneName if the rim-graph element does not have a model attribute.
8. The xml:lang and xsi:schemaLocation attribute SHALL not be used.
9. The xml:id and xml:idref attributes SHALL only be used to convey object references.

Schema Specification

This section specifies a detail method for producing a schema from the RIM definition. HL7 may publish schema produced by this method.

Schema Header

The schema starts with the following declaration:

<schema xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
  targetNamespace="[ns]"> 
 <include schemaLocation="[dt].xsd"/>

The target namespace of the schema is "urn:hl7-org:v3-rim". The data types schema is "datatypes.xsd" for data types R1 ("datatypes-r1.1.xsd" is also allowed), and "iso-21090.xsd" for data types R2.

rim-graph Element

The first declaration in the schema is the rim-graph element and its type.

 <element name="rim-graph" type="RimGraph"/>
 <complexType name="RimGraph">
   <sequence>
     <element name="content" minOccurs="1" maxOccurs="1" 
        type="InfrastructureRoot"/>
   </sequence>
   <attribute name="model" use="optional" type="string"/>
   <attribute name="version" use="required" type="string" default="[ver]"/>
 </complexType>

[ver] is the version of the RIM from which the schema was generated.

RIM Types

The rest of the schema consists of types generated automatically from the RIM. A type is defined for each RIM Class, with the same name, in the same namespace as the elements. The type is derived from the type that matches the generalization of the class.

Either an xml element or an xml attribute is defined for each UML attribute.

For structural attributes, an attribute with the same name is created. The type is either "code" from the datatypes schema or boolean from the schema namespace. The use is "optional" unless the attribute is mandatory, in which case "required".

An element is defined for each non-structural attribute. The name of the element is the same as the attribute. The type of the element is the name of the type of the attribute, with the character "_" substituted for "<", and the character ">" deleted. For RIM versions after version X, the underlying data type name, not the flavor name, is used. The minOccurs on the element is 0. For datatypes R1, the maxOccurs on the element is the same as the maxOccurs on the element in the RIM. For data types R2, the maxOccurs is 1. Attributes are defined in the order they are defined in the UML class.

Any associations that exist are defined as an element on both source and target types. The name is the same as the name of the association, the minOccurs is 0, the maxOccurs is either 1 or * depending on the cardinality of the association, and the type of the element is the converse class. Associations are defined in the order they are defined in the RIM UML, after the attributes.

For the type InfrastructureRoot, the following additional attributes are defined to support references and clone names:

 <attribute name="cloneName" type="xs:string" use="optional">

Appendix #1

R1 to R2 mappings when using data types R2 with rim versions prior to X.

R1	R2
BN	BL
CE	CD
CV	CD