This wiki has undergone a migration to Confluence found Here

New ITS Guide

From HL7Wiki
Jump to navigation Jump to search

Preface

Notes to Readers

This is a work in progress draft, and far from complete

Acknowledgements

Changes from Previous Release

Prerequisites, Assumptions and Conventions

Known Issues and Planned Changes

Should we use the same namespace as XML ITS R1

whether we change the namespace turns on how much difference the new its will make to existing implementations -- it seems to me that much will not need to change, so it could be pitched as a release 2 of the old ITS...

but if you need to function with both, and you are using a binding tool namespace change allows you to separate them

so -- currently they are the same, but a decision is needed

Overview

Introduction and Scope

This document describes the rationale for the decisions taken when developing and maintaining the ITS. This information is provided to support the use of the specification, and is not intended to restrict or extend the meaning of that specification.

 Where there is a difference, the specification takes priority over this document.

Summary

The ITS specification describes the method for creating HL7 implementation models using UML diagrams, XML schema, and (when desired) mappings between an alternative view of a message model and its parent RIM-Based Model (e.g. RMIM).

It uses the same mechanisms to deliver two very different XML representations of RIM-based information structures:

  • Stable, more consistent serialization using generic patterns such as Clinical Statement

for the XML element names. This builds on the success of the stability of the CDA approach to serialization.

  • Reshaped structures where a RIM-based model (e.g. RMIM) is simplified to meet

an implementer view requirement (e.g. mapping to local data models or supporting domain expert review).

The purposes of the new HL7 implementation models include:

  • Providing a stable and consistent serialization across different versions of the same message definition, and between closely related information structures (such as those derived from Clinical Statements, or a Pharmacy DMIM).
  • Enabling clearer model-based XML serialization for HL7 messages (i.e. exposing all serialization rules within an implementation model).
    • Note: This will require changes to the HL7 Abstract Data Types specification.
  • Enabling implementers to simplify XML message representations to support local business purposes while being able to reconstitute the appropriate HL7 global (standard) serialization as needed. Simplification may include:
    • Creating a view of a message model using business information class names (from domain analysis models) instead of RIM-based names, for business expert review / validation of a message model.
    • Reshaping message models to collapse classes.
    • Excluding structural data within message models classes that are not considered useful in a particular message model view (i.e. for a particular purpose).
  • The use of UML-based tooling with HL7 implementation models (e.g. for viewing or for the purpose of model-based automated code generation).

A key component for accomplishing these goals involves the introduction of V3 XML Serialization Models, automatically generated from human-readable annotations on selected RIM-Based Models (RBMs). Serialization Models are intended to support consistent XML representations across HL7 V3 message types and also make the V3 XML rules for serialization more explicit.

Serialization Models allow a message model to be serialized according to cross-message generic rules, as documented by the MIF representation of the generic Serialization Model as well as by ITS decisions documented as Serialization Model annotations.

To support message simplification, a prototype message reshaping tool has been developed and is described in Appendix B. This tool can be used both in connection with this ITS, and also to define intermediate XMLs to help interface systems to the previous ITS, as currently recommended in the HL7 Implementation WIKI.

HL7 shall declare only one Serialization Model (SM) for any given message type to be normative. One of the RIM-based model annotations will identify which SM is to be used in its normative serialization.

Design Principles

  • The transform from the abstract model to the instance should be as simple as possible.
  • The instances should be pleasing to the eye of a human reader.
  • Names should be determined in the abstract model, not generated by the ITS
  • Without compromising other principle listed here the instances should be as small as possible.
  • The ITS should define the set of valid instances for a V3 artefact, and a W3C schema that describes that set. Every valid instance must be schema-valid against the defined W3C schema for that instance. It is also noted that other schemas may be used during implementations.
  • The normative Schema for each static model artefact should use well supported parts of the W3C schema language.
  • Use attributes to support the population of PSVI.
  • The ITS should support the reuse of components in implementations.
  • The depth of nesting in the instances should be a shallow as possible.
  • For each static model artefact there will be a UML model defined that expresses the structure of the XML instances, and that is compatible with UML-based case tools.
  • The CMET references and Wrapper boundaries should not be transparent in the instance.
  • Choices should be transparent in the instance - thus a class should appear in the instance in the same form whether or not it is part of a choice. This is to allow for forwards compatability when choices are introduced into models and to reduce the level of nesting
  • New - Lloyd - The ITS should support modeling constructs provided by the HDF including potential introduction of new layers of wrappers, use of models for multiple purposes (CMETs, payloads, templates), exitable CMETs and the migration of RMIMs, HMDs and MTs to CIMs.
  • Issues
    • which UML case tools are supported, and what for?

Addressing implementation requirements

Implementers have raised the following issues with XML ITS R1:

  • XML element names for the same concepts are different in related messages.

This is a result of taking the XML element names from RMIMs (message models).

  • XML element names are inconsistent across different versions of the same message.

While this does make validation of individual message types easier with schema, it makes it harder to create reusable message processing code.

  • Numerous changes to the data types within one ITS release.

These are not confined to ITS changes. There are places where modelling changes will simplify implementation, but to maintain stability, it is important that such changes are made alongside an ITS revision.

  • The schemas generated produced by the (XML ITS R1) HL7 Generator tool are not ideal

for the production of WSDL specifications in the form that some implementers would prefer. This is a result of the nested pattern used for wrappers, rather than the use of headers.

  • A large number of fixed data items in many message specifications.

The rationale for these were not well understood by many implementers, who regarded them as error-prone overhead. The reciprocal benefit of stable XML element names was not delivered, except in the case of CDA.

  • Default values are not widely used in the specifications, because of a concern that

some implementations will not de-reference the specifications correctly, so the instance must directly include all significant information. This requirement that the instance can stand alone has a high cost in terms of message size, and also in an increased learning curve for implementers.

Explicit Serialization Models, particularly if expressed in a industry standard formalisms such as Unified Modelling Language (UML) and W3C schema (XSD) should be easier for implementers to understand than a narrative specification.

Reducing the number of RIM-based models that form the basis for serialization rules should increase the consistency and stability of wire formats encountered within a given V3 release. Annotating models specifically for the purpose of setting serialization rules may also provide the opportunity for HL7 to streamline the information it mandates is sent over the wire in conformant implementations (e.g. HL7 guidance to implementers related to the inclusion or exclusion of structural codes required in a V3 message instance has changed over time and is still not absolutely clear with respect to the rationale given specific implementation requirements – i.e. it may be the case that some domains require fewer structural/semantic information in instances than others).

Maintaining a set of Serialization Models that graphically summarise schema information and support detailed annotations for implementers may also be easier for HL7 to keep up-to-date and to link with other related policies and documents (e.g. element name sorting protocols).

UML and XSD views of Serialization Models should support implementer requirements for ease of interpretation (using an industry standard model formalism) and the potential use of UML-based code generation tools.

The changes to the data types necessary to support model-based serialization should also avoid some of the hand-crafting and lack of commercial tools support experienced in XML ITS R1.

This ITS also provides a method that documents mappings between a ’simplified’ model and its parent. This type of mapping should also support creating transforms for translating between this ITS and XML ITS R1. Such transforms may be necessary in ’hybrid’ implementation environments.

Model-based validation

One implication of establishing Serialization Models is that message-level models (like specific document models) become constraint patterns for semantic validation (rather than the direct basis for serialization).

This means that message and document instances will need to identify the appropriate constraint pattern for validation purposes. The exact mechanism for achieving this should be found within the V3 Templates specification.

To summarize, Refined Message Information Models (RMIMs) and message types become Standard Validation Patterns useful for application-level conformance assertions. HL7 Templates remain local validation patterns that set conformance rules according to local business requirements. Note that the only difference between an HL7 Template and a Standard Validation Pattern is the fact that the latter is approved by HL7 ballot.


Specification Walkthrough

Serialisation of HL7 Classes to XML

HL7 Class

Each HL7 class is named using the formal naming conventions defined

HL7 Choice structures

There has been long discussion over whether choices should be represented in the instance using an element. On balance there does not seem a strong enough case for adding the extra layer to the instances.

  • Reasons to have an extra layer of nesting
    • The representation of the XML Schema and UML diagram is closer to the RMIM diagram. (There is no need to duplicate the associations that come off the associations so that they are available on each of the child classes. This may help code reuse).
    • It is clear in the instance which associations come off the choice, and which come off the classes within the choice (but when does this matter?).
  • Reasons NOT to have an extra layer of nesting
    • The extra layer of nesting would result in more verbose instances
    • When adding an alternative class to a model (eg introducing a choice by unrolling a class), the new layer in the instances would need to be added to existing implementations, breaking backwards compatibility. While there are many things that break backwards compatibility and this form of incompatibility is unlikely to be the only one as new versions of HL7v3 static models are produced, each one makes maintenance a little harder.

HL7 attribute

HL7 model boundary

The attraction of representing the model boundary in the instance is that it would simplify the naming problem for the classes at the root of a referenced model. These names are currently determined at the time of binding, creating a name for the association that is derived from a combination of the structural attributes of the relationship and the distal class.

However this introduces a complexity to the UML and XML Schema representations of the instances since the model boundaries are not assumed to be represented in the instance in these technologies.

Introducing an element for the model boundary would also increase the size of the instance and depth of nesting.

On balance the simplified naming did not justify the extra size and modelling complexity that an explicit element would have introduced.

Reshaping of RIM based Models

This ITS allows implementers the option of carrying out a sequence of steps to restrict and change the shape of an HL7 RIM-Based Model (e.g. RMIM) to suit various local business purposes. These optional steps may be taken with the intention of making the model easier for domain experts to understand, or easier to map onto healthcare IT systems. Often, it may be desirable to provide a view of a message model that mimics the domain analysis model as much as possible, in order to demonstrate the mapping or traceability between requirements and message design models.

Alternative views may also make XML message instances based on the reshaped model smaller and easier to read than instances of the full HL7 XML ITS. Such serializations, however, would not be conformant to the V3 Standard. The use of simplified XML message instances may only be done at the users’ risk (and may only be appropriate by agreement within small and isolated communications scenarios which are not likely to be extended in scope in future).

Alternatively these instances can be used as a step towards implementing the standard ITS. A supplier-specific simplified model can be produced and may be targetted more easily by that supplier’s data source. An automatic transform is then available to convert these instances to the more complex standard ITS as needed.

Any simplification steps taken to provide an alternative view of a RIM-Based Model shall be recorded as mappings between the original model and its simplified view.

A prototype RIM-Based Model reshaper tool is available that produces the following outputs:

  1. The mappings between the RIM-Based Model and its simplified alternative, in a table-like XML form (which can be read back into the tool to do further reshaping)
  2. An HL7 Model Interchange Format (MIF) file defining the reshaped structure
  3. An example XML message using the full HL7 XML ITS R1, with instance values input by the user
  4. An exemplar XML message in the simplified XML, using the same instance values

The two exemplar XML files, simplified and original, are semantically equivalent to one another. This may be demonstrated by automatically translating from full (RIM-Based) XML ITS to simplified XML, and vice versa.

The reshaping tool, being an experimental tool built for the purposes of evaluating a range of proposals for the new ITS, has some capabilities which we now do not think are appropriate or necessary for the new ITS. These capabilities may be relevant for other purposes – notably for producing local reshaped messages as an intermediate XML along the way to XML which is conformant, either to the previous ITS or the new XML ITS.

One of these capabilities is the capability to restrict a model – a step which might normally be done in other stages of modelling, but which can also be done in the reshaping tool. The following options may be taken when restricting a RIM-Based Model:

  • Restrict the minimum and maximum cardinality of any property or association to a smaller subset of the line [0..1..*] (e.g [min..max] = [0..1] can be restricted to [0..0] or [1..1] )
  • Constrain any leaf property (= RMIM structural attribute, or leaf property within a V3 data type) to a fixed value

The following options may be taken when simplifying a RIM-Based Model:

  • Collapse any association with maximum cardinality = 1, so that the two classes at either end of the association become the same class
  • Rename any class, property or association
  • Remove any property with a fixed value
  • Remove any property or association with minimum cardinality 0 (this is equivalent to restricting its cardinality to [0..0] )

(The collapse of any association with maximum cardinality = \* (unlimited) is not an option because single-valued properties of the inner merged class would become multiple-valued properties of the merged class.)

The reshaping operations can be done either on parts of the RMIM proper (i.e. on classes described in the RMIM MIF file), or on classes which represent the structure of the V3 data types (taken from the data type schema). These are called ’data type classes’.

Representing simplified data type classes

Another capability of the reshaping tool, which goes beyond the capabilities needed for the new ITS, is the ability to restrict and reshape within V3 data types, and more generally to reshape across model boundaries.

For the purposes of the new ITS, we would not expect general restriction or reshaping within data types; we would expect to see a standard set of mappings between the data types of the previous ITS and those of the new ITS (as far as that is possible) supported by two-way translation capability provided, for instance in XSLT. For local reshaping purposes (i.e. simplified messages which do not go on the wire) more general restriction and reshaping within data types may be useful.


Semantic effects of simplifying

If only the reshaping steps allowed as above are done, then the simplified or alternative model should be semantically equivalent to a restricted RIM-based model, in the following sense:

  • Any valid simplified model instance can be automatically translated to an instance of the restricted RIM-based model (which is also an instance of the full RIM-based model)
  • Any valid instance of the restricted RIM-based model can be automatically translated into and instance of the simplified alternative.

The reshaping tool allows collapsing of associations with cardinality \[0..1\]. This introduces some subtle semantic issues which we may wish to keep out of any new ITS definition of messages on the wire. If, during the reshaping, any associations with cardinality \[0..1\] have been collapsed, then:

  • In some cases, translation of a DAM instance to an RMIM instance may be indeterminate, in that the RMIM instance may or may not contain an instance of some class (which has no property values or further associations, so does not carry any property value information)
  • Valid DAM instances must obey some constraints between the cardinality of different properties in different parts of the DAM tree.


Abstract Serialisation Model

What is a Standard Validation Model?

For V3 Messaging the Standard Validation Model is the static model that is referenced in the interactions within the ballot, and as such is the message types that we know and love.

They are called Standard Validation Models because they are the most constrained model that has been defined by HL7 to which the instance conforms.

They are called Standard Validation Models because the primary purpose for the models is to allow validation of the instances to ensure that they conform to the standard specification. Having said that it is recognised that in practice many implementations of the XML ITS R1 used the XML element names to drive processing decisions, and it is expected that some implementations will use the Standard Validation Model identifiers to drive processing decisions.

Model Node references

In order to reference the Standard Validation Model a mechanism is needed to specify the model and the node within that model that is being referenced. This has been attempted in a number of different ways, and this section will present the approaches that have been used, to allow a choice to be made.

Requirement for Serialization Models

  • To use this part of the ITS there is a need to establish and normalize V3 Serialization Models to set the wire format rules for all HL7 message and document designs. (Note: This is likely an appropriate joint work item between INM and MnM.)
  • Candidate Serialization Models include:
    • One for all clinical domains (e.g. CDA, Patient Care, Lab)
    • Medications
    • One for Administration and Finance
    • Shared Messages
  • Limiting the number of Serialization Models should also increase the ease

of harmonizing [creating consistent serialization rules for] common concepts across them (e.g. the Clinical Statement Pattern, CMETs).

Informal Extensions

Backwards and Forwards Compatability

The use of schema processors

Implementation Issues

How are reshaping specifications shared

It has been suggested that we can find ways to generically share the compression approach (via embedded info in a WSDL schema or something) so that applications could negotiate without human intervention.

This is an interesting suggestion that would allow those that want to do RIM-based processing to do it, without the RIM information being expressed on the wire, and so allowing us to address other implementation concerns and reducing message size, both byte-count and node-count.

Relationship to XML ITS Structures Release 1

This section documents the differences between this specification and XML ITS Structures R1

Schemas and UML Representations

This specification includes a definition of normative schemas and UML representations for the set of valid instances for a message.

The Use of Schema Processors

XML ITS R1 said "Schema processing is not a conformance requirement although this specification has been designed to make schema processing beneficial." This specification says "Schema processing is not a conformance requirement although this specification has been designed to support schema processing."

Reshaping of RIM based models

This is a new concept that was not included in XML ITS R1

Abstract Serialisation models

This is a new concept that were not included in the XML ITS R1

Glossary entries

The entries here are words or phrases that are used inthis document and need to be defined in the Glossary

Questions for Publishing

Examples