RIM ITS Specification
Contents
document to do
- Keith wants to know about canonical representation to foster digsig. Important point - to be clarified
- rewrite below the annotated examples section to be consistent with the annotated examples section
Ballot Notes
The development of this ITS should not be taken as intent or evidence that it will supplant or replace the pre-existing XML ITS. Such decisions may be considered in the future when there has been some practical experience with a RIM ITS in XML, 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. Versions "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, known as the 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.
Annotated Example
Simple RIM Graph
The following example XML introduces the RIM ITS. The example was auto-generated from the MIF for the interaction PORX_IN010380CA.
<?xml version="1.0" encoding="UTF-8"?> <rim-graph xmlns="urn:hl7-org:v3-rim" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="0226">
All RIM ITS instances start with the xml element rim-graph in the namespace "urn:hl7-org:v3-rim". The rim-graph element has a mandatory attribute called "version" which identifies the version of the RIM on which this RIM graph is based (see note below about RIM inter-version issues). This example shows the rim-graph element as the root element of the XML document, but this need not be the case - one or more RIM graphs may be contained within a greater XML instance, such as a SOAP message. This specification distinguishes between the scope of the XML document and the scope of the RIM graph - some things must be found within the greater XML instance, and some things within the single RIM graph.
The rim-graph element has a single child element called "content".
<content xsi:type="Message">
The content element is defined of type InfrastructureRoot, which is an abstract type in the RIM, so the xsi:type attribute is used to indicate it's actual type, which must be one of the classes defined in the RIM. Starting from the content element, every element in the XML corresponds to either an attribute or an association of a RIM class, and therefore has a corresponding type of either a V3 data type or a RIM class that defines its content model.
First, we have the attributes. The RIM defines two kinds of attributes: immutable and mutable.
Immutable attributes are fixed for the life-cycle of the object. These attributes all have simple types such as CS or BL, and are represented as xml attributes on the xml element representing the class. The attributes have no namespace, and may appear in any order.
<content xsi:type="Document" classCode="DOC" moodCode="EVN">
(There are no immutable attributes on Message, so we use a Document based example instead).
The mutable attributes are represented by an XML element with the name of the attribute in the namespace "urn:hl7-org:v3-rim".
<realmCode code="CA"/>
The attributes must appear in the order in which they appear in the RIM UML class model.
<id root="D31D0FE0-B8BF-40E7-8669-D9E15372F096"/> <creationTime value="20080901124354.649-1000"/> <securityText>Some plain text goes here</securityText> <responseModeCode code="D"/> <versionCode code="V3-2008N"/> <interactionId root="2.16.840.1.113883.1.6" extension="PORX_IN010380CA" displayable="true"/>
The content model for the element is that defined by the XML representation of the corresponding RIM data type. There is two different data types, for R1 and R2. Prior to RIM version X, the RIM is based on the R1 data types, and the applicable content model is the XML ITS for data types (reference...). After this RIM version, the ISO 21090 data types are used (reference..) (It's also possible to use the ISO data types with earlier versions of the RIM, see further below).
<profileId root="9B8CA482-E5ED-4691-89DD-272EC2F29B66"/> <profileId root="FA0FE413-56DE-466B-B052-0D4CED2F08A4"/>
For data types R1, where the attribute has the type SET<T>, BAG<T>, LIST<T> there will be one XML element for each item in the list. If the type is GTS, there may be one or more elements depending on how the GTS is represented. For data types R2, there will only be one element and the additional content will be contained inside that element. The profileId attribute would look like this in data types R2:
<profileId>
<item root="9B8CA482-E5ED-4691-89DD-272EC2F29B66"/>
<item root="FA0FE413-56DE-466B-B052-0D4CED2F08A4"/>
</profileId>
Then there is the rest of the attributes:
<processingCode code="D"/> <processingModeCode code="T"/> <acceptAckCode code="AL"/>
After the attributes, we have the associations
<communicationFunction typeCode="RCV">
Each association is represented by one or more XML elements with the name of the assocation (as shown in the RIM UML class model) in the namespace "urn:hl7-org:v3-rim". Note that the name of the association is the RIM name (such as player or scoper), not the name assigned to the association in some other clone model, like in the XML ITS). The associations must appear in the order in which they are defined in the RIM UML class model. The order of the associations is not apparent in the graphical representations of the UML class model, but it does exist. The order may be determined by any one of the following methods:
- reading the RIM standard
- reading the RIM ITS schema published by HL7
- consulting the RIM XMI representation
- consulting the RIM MIF representation
The content model of the element is that of the class to which the association points. If the class the association points to is the same the class in the RIM - such as for the communicationFunction, then no xsi:type is required. However if the association points to a class such as Act, and another more specialized class, such as SubstanceAdministration, is used in it's place, then an xsi:type is required in the instance.
The CommunicationClass has an immutable attribute called typeCode. Immutable RIM attributes are represented as simple XML attributes instead of elements. Note that the RIM defines which attributes are immutable). Only attributes of type CS and BL are immutable, and these are represented by simple codes or boolean values (true or false).
<telecom value="http://10.0.0.1:1001"/> <entity classCode="DEV" determinerCode="INSTANCE"> <id root="1.2.3.4.52" extension="A12345"/> <name>UniqueName2</name> </entity> </communicationFunction> <controlAct xsi:type="ControlAct" classCode="CACT" moodCode="EVN">
Note that the xsi:type attribute here is redundant - the only possible type is ControlAct, but it is not wrong to include it.
The rest of the instance proceeds on a similar basis, and no further annotation is needed until we come to
<outboundRelationship xsi:type="ActRelationship" contextConductionInd="true" contextControlCode="AP" typeCode="COMP">
<target xsi:type="Observation" classCode="POSCOORD" moodCode="EVN">
<value xsi:type="PQ" value="1.3" unit="mmol/L"/>
</target>
</outboundRelationship>
Here, an act relationship points to an Observation class. The value attribute has a type "ANY" so will almost always have an xsi:type specifying the actual type. The sole exception is when the value is unknown, in which case an instance of
<value nullFlavor="UNK"/>
is valid (this is also allowed for other nullFlavors).
</controlAct> </content> </rim-graph>
Templates
Most RIM content is further constrained by additional models. Such models are considered to be templates that apply additional rules over and above those defined in the RIM class model. Some of the models are defined as static models using the formal methodology and tools defined by HL7, while others are defined more informally either by HL7, realms or other authorities. One feature of this arrangement is that RIM classes often conform to more than one such model, and the fact that they conform to these models is of interest, and worth noting in the instance by marking the RIM classes with the identifiers of the templates.
Generally, there are two reasons to note such conformance in the instance itself. One is to allow validation engines to confirm that the conformance claim is valid (which they can do if they identify the template and have some machine processable representation of it available), and the other reason is to allow readers of the content to process it much more quickly and easily. When a template identifier is identified, the meaning the content is already known, and the instance may be processed more quickly than is possible if the meaning of the codes must be determined (i.e. sometimes by subsumption, for instance). (Foot?)Note that it has been claimed that this a bad or dangerous process, because it means that semantic interoperability is lost; but this is not case, as the processing is still based on the semantics of the instance, but the template is used to identify the semantics more quickly. The important question is what happens to rim classes that do not identify their conformance to any particular (or recogized) template. Different implementation contexts will have different requirements and rules in this regard.
The RIM ITS uses the XML namespace system to represent templates. The following example is based on the standard CCD example, and demonstrates how the template system works.
<?xml version="1.0" encoding="UTF-8"?> <rim-graph xmlns="urn:hl7-org:v3-rim" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="0226"> <content xsi:type="Document" xmlns:cda="ii:2.16.840.1.113883.1.3:POCD_HD000040" xmlns:n1="urn:oid:2.16.840.1.113883.10.20.1" templates="cda:ClinicalDocument n1:root">
This is a rim graph where the root object is a Document. Firstly, the document object conforms to the CDA specification. A namespace is defined for the cda specification, which is identified by the token POCD_HD000040 in the identifier space identified by the OID 2.16.840.1.113883.1.3. (All HL7 static models where the standard naming system applies are in that OID).
- todo: what scheme? ii: is not defined anywhere, so what should it be? btw, see hl7-att in abstract R2.
Additionally, as a CCD document, the document object conforms to the template "2.16.840.1.113883.10.20.1" defined in the CCD specification. So a corresponding namespace is defined for that too.
The templates attribute is a series of QName tokens that identify the templates that the object claims to conform to. For the CDA template, the name is the name of the clone class in the CDA static model. For the CCD template, the template only identifies a single object, and has no extension; accordingly the designator "root" is used to identify this.
- Todo: that this breaks down to 'root' is a bit of a pain. We're trying to be elegant here :-(. An alternative is to break out the CCD templates by pulling out a CCD common root - such as 2.16.840.1.113883.10.20. Then all the inner templates become ccd:1, or ccd:3.4, for instance. That would be pretty cool, but I'm not sure that breaking an oid into root and tail like this would go down well. And the CCD document isn't written to make this kind of use really useful.
One use of the templates attribute is to carry the clone names that would be represented in the XML ITS, as shown in the CDA example here. Transforming from the XML ITS instance to the equivalent RIM ITS representation is a trivial process, but the reverse transform is not so trivial. The RIM Object graph must be speculatively matched against the constraints specified in the XML ITS static 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 readers 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 use the templates attribute as shown above to carry this information and save the reader from performing this speculative matching. This applies to any templates, not just the model that the XML ITS arbitrarily anoints. The templates attribute is optional, though its presence, and/or it's use with particular template models may be required by trading partner agreement.
References
Add an annotated example that shows how references work.
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?).
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 entry points, 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
- 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
- The XML instance SHALL commence with a single element called "rim-graph" in the namespace "urn:hl7-org:v3-rim".
- The rim-graph element SHALL have a version attribute documenting the version of the RIM upon which it is based.
- The rim-graph element MAY have a model attribute specifying the model to which the data conforms.
- The rim-graph element SHALL have a single child element called "content" in the same namespace as the rim-graph element.
- The content element and it's contained content SHALL be valid according to the RIM specification.
- Elements representing RIM objects MAY have a cloneName attribute specifying the clone to which they conform in the specified model.
- Elements SHALL not have a cloneName if the rim-graph element does not have a model attribute.
- The xml:lang and xsi:schemaLocation attribute SHALL not be used.
- 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 |
