This wiki has undergone a migration to Confluence found Here

Difference between revisions of "UML ITS Technical"

From HL7Wiki
Jump to navigation Jump to search
Line 7: Line 7:
 
  [[RBM]] <--[[UML ITS Policy|Policies]]--> [[XUM]] [[Implementable Models]] (UML diagram <-> Schema)
 
  [[RBM]] <--[[UML ITS Policy|Policies]]--> [[XUM]] [[Implementable Models]] (UML diagram <-> Schema)
  
The output of the ITS can be used for code generation.
+
The output of the ITS can be used for code generation. It will be tested with common tools. The XUM works with the commonly used tools, and it correctly specifies the wire format. It doesn't completely describe the validation rules for the message, no schema or UML model will be able to do that, because the HL7 models rely heavily on terminology.  A XUM consists of a pair of schemas and UML diagrams that specify the exact same wire format, implementers can code generate from them and exchange data. WYSIWYG: What you see in the schema or in the diagram, is exactly what goes on the wire.  
  
 +
There is existing work outside HL7 on the question of transforming from UML diagrams to an XML instance or a schema. The UML ITS is intended to leverage this work
 +
(One of the existing issues is that UML to XSD transform requires sequencing of the associations, which is a "bit of magic", but does need to be represented explicitly).
  
The UML ITS transforms a HL7 model to a a [[XUM]] (the implementable model, expressed both in terms of an implementable UML model as well as an implementable schema) and then to a message. The XUM works with the commonly used tools, and it correctly specifies the wire format. It doesn't completely describe the validation rules for the message, no schema or UML model will be able to do that, because the HL7 models rely heavily on terminology.  A XUM consists of a pair of schemas and UML diagrams that specify the exact same wire format, implementers can code generate from them and exchange data. WYSIWYG: What you see in the schema or in the diagram, is exactly what goes on the wire.
+
==Normative==
  
There is existing work outside HL7 on the question of transforming from UML diagrams to an XML instance or a schema. The UML ITS is intended to leverage this work
+
[[XUM]]s will be normative. We do not claim that these are the only model that can apply, but we assert that the XUM is a reliable correct definition of the wire format. Specifically we allow for things such as schema artifacts in the instance of the message. If the message fails schema validation, it is necessarily incorrect. If the  
(One of the existing issues is that UML to XSD transform requires sequencing of the associations, which is a "bit of magic", but does need to be represented explicitly.
+
message passes schema validation, the format is correct, but the actual data contents may not.
  
The transformations that applied during the process from the [[RBM]]s to the wire format are done '''before''' we create the implementable model, so these transforms are made explicit, and there is no surprises for the implementer. The transformation from RBM to XUM is deterministic, so it will be possible to go back from UML to the RBM.
+
It expresses a RIM-Based Model ([[RBM]]) both in terms of a XML schema as well as a UML model. The UML model is the equivalent (or as closely as possible) of the schema and vice versa.
  
The transformation between the [[RBM]] and the implementable model could include optimizations of the model in order to address implementation concerns, e.g.
+
==UML==
*'''Sending of fixed and default values, especially structural codes.'''
 
*'''Flatten RIM constructs''', e.g. telescope attributes of an associated class into other class,
 
*'''Add business (or: local) names'''. e.g. for "effectoveTime"
 
  
These issues are discussed in [[optimising wire formats for users]]
+
Each XUM is represented by a single UML class diagram with a single UML package. The UML representation of the XUM may use the following UML constructs:
 +
* Classes with Attributes. Operations are not supported since these are representations of wire formats with no behavior.
 +
* Parameterized classes with one class parameter. All parameterized classes are collections
 +
* Constraints using OCL in notations attached to the class.
 +
* Constraints must include the context <class name>
 +
* Generalization associations
 +
* Named composition associations (represented as by value in XML)
 +
* Named associations (represented as by reference in XML)
 +
* The {xor} notation (? For discussion. this is a neat construct for us, but not very well supported. However it may not matter, we can encode as an {xor} constraint and an OCL constraint)
 +
* The stereotype <<enumeration>> for enumerations
 +
* The stereotype <<io>> for marking entry points.
 +
* The inbuilt types from the OCL 2 kernel, or any types found in other XUMs which must be explicity accessed as UML packages
 +
* Comments in attached Notations.
  
The new UML ITS creates a model that only contains that which is needed on the wire. It contains less XML elements than the XML ITS. I doesn't follow RIM gramatical structure/grammar, they are not needed on the wire. This approach is possible because you can go back from the implementable model to the RBM.
+
The UML representation will be published as a GIF image, and SVG picture, and an XMI file.
  
Code generation based on flattened (UML-) implementable model.
+
==XML==
  
==Serialization Details==
+
Each XUM is represented by a single schema. The XML schema representation of the XUM may use the following schema constructs:
 +
* Complex Types
 +
* Element and attribute definitions
 +
* Global elements for entry points
 +
* Simple Types for enumerations
 +
* Sequences
 +
* Choices for choices
 +
* Schematron rules for constraints
 +
* The inbuilt types from the schema standard, or any types found in other XUMs which must be explicity imported as schemas
 +
* Comments in AppInfo annotations
  
Which RBM do we use (RIM, DMIM, RMIM, MT, template?) for serialization. Same concept at every point. XML ITS uses MT. DMIM may be best level. fits best with SOA services model. There are arguments for RIM based serialization without using local names. Lots of different names makes implementation more difficult, e.g. dozens of xPaths to identify things in similar model, more need for documentation. If one chooses RIM, then all other models become "templates". Raises issue of assigning semantics to clone names again, many current models aren't deterministic.
+
The schema representation will be published as an xsd file. All the schemas will be in the same namespace.
  
Reading the instance with the definition. Need to consult the definition on order to understand the instance.
+
==Relationship between XML and UML==
  
The relationship between the instance and the meaning indeterminant in the absence of the model.
+
The UML diagram and the schema will be as isomorphic as possible. Other than in the constraints, the two representations will be identical. There will be simple rule for describing which UML attributes are represented as XML attributes, and which UML attributes are represented as XML elements
*RIM based, no need for any definition;
 
*full fledged RBM-based serialization including all structured codes, no need for definition;
 
*RBM-based serialization without structured codes, need to consult definition - current positition
 
  
==Related==
+
==Elements vs Attributes==
  
The proposal has associated proposals for related issues (that are not purely ITS-related, but are a prerequisite for the ITS to work). These are:
+
It's still not decided whether to use XML elements or XML attributes in the new ITS.
*Datypes R2 Isues
 
*nullFlavor cleanup. Cascading of associations which lead up to a class with an important attribute. Can be dealt with by making everyting mandatory BTW.
 
*templateId
 
*(general approach) Could be RBM -> Flattened Model -> apply any ITS
 
*(XML ITS) create normative schema?
 
*Sutructured attribute. Currently no need to be on the wire - requires that receiver has to know model in order to process the message. Generic processing requires that one knows the struc codes (e.g. Java SIG code), looking them up carries implementation /performance overhead. Want to have everything in the instance. Discussion in MnM.
 

Revision as of 23:54, 14 September 2006

The UML ITS is a technical infrastructure for making V3 wire formats easier to implement.

The XML ITS includes a number of 'secret' transforms (actually, they are not secret, but they are exceedingly poorly documented). The UML ITS proposes to be extremely specific about the wire format, in the recognition that it's the wire format that users actually finally encounter and must master. It's goal is to be able to go to an implementer and offer them a "thing" they can use, an implementable model. The implementable model will be normative and will be published as UML and XML schema.

There may be a number of implementation decisions and transforms made between the RBM and the on-the-wire format. These are made before the UML and schema are built, and are explicit in them. These changes are discussed in UML ITS Policy.

RBM <--Policies--> XUM Implementable Models (UML diagram <-> Schema)

The output of the ITS can be used for code generation. It will be tested with common tools. The XUM works with the commonly used tools, and it correctly specifies the wire format. It doesn't completely describe the validation rules for the message, no schema or UML model will be able to do that, because the HL7 models rely heavily on terminology. A XUM consists of a pair of schemas and UML diagrams that specify the exact same wire format, implementers can code generate from them and exchange data. WYSIWYG: What you see in the schema or in the diagram, is exactly what goes on the wire.

There is existing work outside HL7 on the question of transforming from UML diagrams to an XML instance or a schema. The UML ITS is intended to leverage this work (One of the existing issues is that UML to XSD transform requires sequencing of the associations, which is a "bit of magic", but does need to be represented explicitly).

Normative

XUMs will be normative. We do not claim that these are the only model that can apply, but we assert that the XUM is a reliable correct definition of the wire format. Specifically we allow for things such as schema artifacts in the instance of the message. If the message fails schema validation, it is necessarily incorrect. If the message passes schema validation, the format is correct, but the actual data contents may not.

It expresses a RIM-Based Model (RBM) both in terms of a XML schema as well as a UML model. The UML model is the equivalent (or as closely as possible) of the schema and vice versa.

UML

Each XUM is represented by a single UML class diagram with a single UML package. The UML representation of the XUM may use the following UML constructs:

  • Classes with Attributes. Operations are not supported since these are representations of wire formats with no behavior.
  • Parameterized classes with one class parameter. All parameterized classes are collections
  • Constraints using OCL in notations attached to the class.
  • Constraints must include the context <class name>
  • Generalization associations
  • Named composition associations (represented as by value in XML)
  • Named associations (represented as by reference in XML)
  • The {xor} notation (? For discussion. this is a neat construct for us, but not very well supported. However it may not matter, we can encode as an {xor} constraint and an OCL constraint)
  • The stereotype <<enumeration>> for enumerations
  • The stereotype <<io>> for marking entry points.
  • The inbuilt types from the OCL 2 kernel, or any types found in other XUMs which must be explicity accessed as UML packages
  • Comments in attached Notations.

The UML representation will be published as a GIF image, and SVG picture, and an XMI file.

XML

Each XUM is represented by a single schema. The XML schema representation of the XUM may use the following schema constructs:

  • Complex Types
  • Element and attribute definitions
  • Global elements for entry points
  • Simple Types for enumerations
  • Sequences
  • Choices for choices
  • Schematron rules for constraints
  • The inbuilt types from the schema standard, or any types found in other XUMs which must be explicity imported as schemas
  • Comments in AppInfo annotations

The schema representation will be published as an xsd file. All the schemas will be in the same namespace.

Relationship between XML and UML

The UML diagram and the schema will be as isomorphic as possible. Other than in the constraints, the two representations will be identical. There will be simple rule for describing which UML attributes are represented as XML attributes, and which UML attributes are represented as XML elements

Elements vs Attributes

It's still not decided whether to use XML elements or XML attributes in the new ITS.