Domain Information Model Artifact Definition

Return to Artifact List

DIM Initial Build

Definition and Purpose

Put text here

SAIF Matrix Location

Row(s)

• Logical (PIM)

Column(s)

• Information

Audience

Health Care Information Technology (IT) Audiences:

• System designers and architects
• System vendor management

Applicability

Text

Rationale: More text

Requirements, Relationships and Content

1. This type of model MUST include the set of classes, attributes and associations from the parent (derived from) model that represent the information needed to support interoperability in the domain or project that this model will support.
   1. RationaleDerived Models must use the RIM-derived model content needed to support the interoperability project in question.
2. This model MUST maintain a degree of abstraction appropriate to the level of the model, remembering that models derived from this model can be more specific.
   1. Rationale Large models with myriad classes may obscure the core patterns and concepts that need to be represented in a particular DIM, SIM or other model.
3. This model must include (or be accompanied by) a "design walk-through" that documents the function of each class and "class-equivalent" (see Content section below) in all models, and each attribute in SIMs.
   1. Rationale Such walk-throughs are critical to the understanding of an information model, and are required as part of the ballot for such models.

Relationships and traceability

1. All of the contents of this Domain Information Model MUST be derived from an artifact whose type is a Reference Information Model. Derivation rules are discussed under Content Constraints below.
   1. Rationale These derivation relationships that ultimately derive from the RIM are at the heart of HL7's V3 model-driven methodology and architect.

• This model and its attributes must be bound to content from a specific "abstract" data type model formally adopted by HL7.
  • Rationale: The data structures that derive from the RIM draw much of their "type" information from data types assigned to RIM attributes.
• This model and its encoded attributes must be bound to content from a specific Vocabulary Model.
  • Rationale: Over 40 per-cent of RIM-derived attributes carry encoded values. The expected terminology binding for those attributes must be carefully defined.
• This model and its common interfaces (CMET references) must be bound to content from a specific Interface Model.
  • Rationale: References to a "Common Model" in a SAIF Information Model must be drawn from a package (model) of defined interfaces.
• Traceability of model content (perhaps via the "derived from" model) to content expressed in a Conceptual Information Model from the relevant domain or project.
  • Rationale: Provide traceability from project requirements expressed in a Conceptual Data Model to their realization as part of the model(s) in the PIM and PSM layers.

Artifact types that may or must relate to this artifact types:

• Conceptual Information Model
• Serializable Information Model

Content

• Model data - Defining data (including name, version, responsible party, and description) captured at the model level.
  • HL7-defined properties - Properties that formally extend the definition of a model beyond the UML specifications.
• Association - UML element expressing relationships between classes with UML-specified characteristics such as descriptions, name, association ends, cardinalities, navigability, etc.
  • HL7-defined properties - Properties that formally extend the definition of an association beyond the UML specifications.
• Class - UML element with UML-specified characteristics such as descriptions, name, etc.
  • Attribute - UML element with UML-specified characteristics such as descriptions, name, cardinality, etc.
    • Data type - Type assignment from HL7 data types specification.
    • HL7-defined properties - Properties that formally extend the definition of an attribute beyond the UML specifications.
  • HL7-defined properties - Properties that formally extend the definition of a class beyond the UML specifications.
• Entry Point - A graphical model element that points to a single class that is the root class for serialization of this model, or may be the root class for serialization of derived models.
• Class-equivalent elements - Extensions to UML that are represented graphically and may appear anywhere in the model that a Class can appear. These include:
  • Common Model Reference - Reference to the root class of another model drawn from an Interface Model

  • Non-Common Model Reference - Reference to the root class of another model that is not a member of the Interface Model

  • Stub - A locus for binding to the root class of another model that will be contained within (be the "payload" for) this model.

Artifact Technology

The primary distribution technology for this model SHALL be in a file that conforms to the HL7 Model Interchange Format (MIF).

The Ideal model creation tool for this artifact is defined in the Tooling Considerations section of this document. The "ideal tool" is used as "requirements" in the following discussion of current tooling and alternatives.

Current (April 2011) model creation tool for this artifact

HL7 RMIM Designer in Visio accomplishes all of the functions listed for the ideal tool, except 2., 2.1 and 3.3. This tool is:

• Written in Microsoft Visio VBA (runs in releases 2002, 2003, 2007, or 2010)

• Has configurable editors - Clone [class] Editor, Vocabulary Selection pane, and CMET Selector - all of which
  • Get RIM configuration from a Design Repository via RoseTree DLLs

  • Get Vocabulary configuration from a Vocabulary "core MIF" file via RoseTree DLLs

  • Get data types content and constraints from an RMIM Designer-specific text file

  • Get Interface Package contents from an RMIM Designer-specific text file

• Saves primary content in dual files as:
  • Using Visio "VSD" files as the Visio-readable source and as the primary graphic storage

  • Using an HL7-defined XML file of all content and annotations that includes all data needed to create a MIF representation.

• Has VBA functions to extract the graphic data as PNG files and a corresponding "mapped overlay" to provide "clickable graphics" that link to textual renderings of the model

• Requires support functions from the V3 Generator to:
  • Create a MIF "output" file that includes graphic data (starting with the XML output from the RMIM Designer), and

  • Produce "table views" of the data to which the mapped overlays link.

Rationale

This information model artifact has several primary characteristics that act as requirements for the selected technology. These characteristics are:

• The model is a UML Class model with extensions to UML to represent:
  • New shapes to represent Entry Points, Interfaces and stubs

  • HL7-defined properties for many elements

• The model must be distributed as a machine-processable model represented in the HL7 Model Interchange Format (MIF) in support of:
  • Using any particular model artifact as the "derived from" source for another model;

  • Support V3 Generator process that creates schemas for HL7 V3 specifications

  • Support V3 Publishing and Normative Edition packaging and publication processes

• The model must be derived from a predecessor model whose ultimate derivation source is the Reference Information Model (RIM)

• The model must declare bindings to:
  • A Data Types Model to which its attributes are bound

  • A Vocabulary Model to define the terminology bindings for its encoded attributes

  • An Interface Model from which its interfaces are drawn

• Within the model the textual representation for properties governing class attributes is governed by the Static Model BNF Grammar specified by the Modeling and Methodology Work Group.

Alternatives

An alternative tool, the NHS-supported Static Model Designer (SMD) has intended characteristics that meet all of the characteristics of the "ideal" tool (except, in the early releases, 2.2 and 3.3) has been under development. As of April 2011, there is not sufficient funding to advance the tool to the point that it could replace the current tool suite.

Content Constraints

Model Derivation Constraints

For Information Models that are derived from either the HL7 RIM (RIM) or from an information model that has the RIM of as one of its derivation ancestors, the Content Constraints are simply stated:

The contents of this model must be either the same as the contents of the model from which it is derived from or a constrained sub-set of the contents of that model.

The obvious question, then, is: What constitutes a "constrained sub-set" of the contents of a model? The answer to this question is found in the rules specified in HL7 Version 3 Standard: Refinement, Constraint and Localization to Version 3 Messages, Release 2 (ANSI/HL7 V3 RCL, R2-2007), approved in August 2007.

(Do not be misled by the term "Messages" in the title of this standard. A "message" is simply a Serializable Information Model (SIM).)

The remainder of this section will summarize the constraint rules that are documented in that standard, and modify them to use SAIF terms. This document does not replace those rules. In general, the process of derivation and constraint reduces the "breadth" of the semantic content of the model, and/or limits the scope of the values for particular elements of that model.

Tooling support for derivation -
It is important to note that although these rules are detailed, the software that HL7 has developed and provided to support development of RIM-derived models, prevents the user from deviating from these rules (or, at minimum warns of variance), by offering "drop-down" selections whose content is determined by the RIM, data types, vocabulary and the previous constraint. Further, the somewhat intricate formal naming algorithm is implemented within those tools and automatically produces valid names.

Primary rules governing derivation
The rules from the Standard are in chapter 2 - Constraints and Annotations which begins as follows. Constraints are the central feature of the derivation process, as they reduce the generality of the base model and focus it on a particular requirement. The constraints that may be asserted against a model element, e.g. class, attribute or association, fall into broad categories that are detailed in the following sub-sections and summarized as:

1. Appearance constraints determine whether a particular model element in the base model must appear in models or messages derived from the base model, and/or whether the element is precluded from appearing therein.

2. Cardinality constraints define the number of repetitions that may occur for a given element.

3. Constraints when "Cloning" classes The process of deriving a new model from another, "base" model, involves the ct of creating a "clone" (copy) of one or more of the classes in the base model. (The term "clone" is used because more than one copy may be created and the properties of the class (attributes, associations, etc.) may be changed in the process.) These are the constraints upon what elements of the "base model" may or must be cloned, when, and how they may be modified when they appear in the new model.

4. Formal naming constraints In an attempt to achieve more consistent models, and to make class names reflect their RIM sub-type (typeCode or classCode values), HL7 adopted a set of Formal Naming rules that affect how things MUST be named in a derived model. (Not included in the Refinement, Constraint and Localization Standard)

5. Type constraints limit the structure or "type" of the element in question. These are constraints placed upon the data types for attributes and upon the use of Common Model Element Types (CMETs) at association ends.

6. Vocabulary constraints limit the set of concepts that can be taken as valid values in an instance of a coded attribute or data type.

7. Other value constraints provide for the declaration of constraints stated as text and, optionally, as testable expressions to establish "business rules", and for the assertion of default or fixed values.

Appearance Constraints

Appearance constraints apply to attributes and associations. The presence of a model element in a derived model depends upon the appearance constraints that are asserted or implied for that element in the base model, and upon the rules for "cloning" classes from a source model to a target model.

There are two forms of appearance constraints that may be set in a model: the declaration that an element is mandatory; and the assertion of a conformance value.

The mandatory inclusion property indicates whether or not a particular element must be present in each instance of serialized model. If the mandatory inclusion property of a particular element is set to "M", the element is mandatory. If an element is Mandatory, then all elements that derive from it in derived models SHALL also be Mandatory.

The conformance property specifies how a model element must be handled by applications. Every attribute and association element in a model has an explicit or implicit conformance property. The property has one of three values: Required, Unspecified or Not Permitted:

• Required (R) - When deriving models, the element must appear in all instances of derived models and must be declared as "Required" in derived models.
• Unspecified (U) - The appearance of this element in derived models is unconstrained. In instances of derived models the element may retain "Unspecified" status, or it may be declared "Required" or "Not Permitted". "Unspecified" is the default value for this property.
• Not Permitted (NP) - This element SHALL not appear in derived models or, it it appears, it MUST also be "Not permitted" in the derived model.

Constraints when Cloning classes

Whenever an information model is derived by constraining another information model, it is permissible to "clone" the classes of the base model. This is true whether one is deriving a DIM from the RIM, a SIM from a DIM, or a SIM from another SIM.

Class cloning is the creation of one or more copies of a base class contained in the source model into the new model. Cloning is the only form of model "extension" permitted under the terms of this section. The following rules apply:

• In order to be a source class for more than one clone in the derived model, a class in the base model:
  • Must be reached by an association whose upper cardinality limit is greater than "1", or that is reached by a "recursive" relationship ( typically when a class (type) is declared to have a "component" relationship to its self).
• In order to qualify as a valid clone of a source class, the clone must obey the following rules:
  • If the source class has been cloned more than one in the derivation, the clone classes SHALL have a new name to assure that they have unique names within the derived model.
  • The clone may contain only attributes that are also part of the source class
  • The clone shall only use associations that are valid for the source class and are present in the base model
  • The cardinality and mandatory constraints for elements in the clone class cannot be less constrained than the equivalent elements in the source class
  • The vocabulary domains declared for any coded attributes in the clone must be identical to, or a subset of, the domain asserted in the source class, and if the coded attribute is "CNE" the cloned attribute must also be "CNE"
  • The clone need not include attributes or associations unless they are "Required" or "Mandatory" in the source model, regardless of their cardinality
  • The clone may not include attributes or associations that have a conformance value of "Not Permitted" in the base model

Formal Naming Constraints

In an attempt to achieve more consistent models, and to make class names reflect their RIM sub-type (typeCode or classCode values), HL7 adopted a set of Formal Naming rules that affect how elements MUST be named in a derived model. A more detailed reference on Formal Naming is on the Wiki. The following extracts the major features and rules of that document.

Through Harmonization, HL7 has defined an algorithm for deriving formal names from model constraints. The specifics of this algorithm are documented on the HL7 G-forge site. The modeling tools used by HL7 include an implementation of these algorithms that automatically names any element that is required to use the "formal Name."

Uniqueness Requirements

• Each class in an information model must have a unique name.
• Each attribute within a class, including attributes inherited through a generalization-specialization relationship, must have a unique name.
• Each association from a class must have a unique role name at the far end (at the class to which the association is going).

Semantic Integrity Requirement

The semantic meaning of any given derived class (clone) SHALL be determined solely by the value of the controlling attributes (classCode, typeCode, etc) of the class. Thus, the name of a class or association SHALL not be required to understand the semantic meaning of the class.

Naming style

• With one exception, any name that has multiple elements SHALL have those elements combined with "camel case", such as "camelCase" or "CamelCase".
  • The sole exception is in the naming of Common Model Element Types (CMETs) in which the opening characters is a single upper case character that designates the RIM class that is the root of the CMET, followed by an underscrore ("_") followed by a proper class name.
• All class names SHALL be represented in UpperCamelCase, where the first character of the name is alphabetic.
• All attribute and association names SHALL be represented in lowerCamelCase, where the first character of the name is alphabetic.
• Where an information model includes two classes with identical or similar controlling attributes, the names of those classes may be disambiguated by appending numeric or other suffixes.

Naming derived classes (clones)

1. The formal names for class clones are:
   • based upon the constrained value of their classCode, for clones of Act, Role and Entity, (qualified by moodCode and determinerCode for Act and Entity, respectively); or
   • based upon the constrained value of their typeCode, for clones of ActRelationship, Participation or RoleLink; or
   • the RIM class name, for clones of any other RIM class.
2. For classes cloned from the ActRelationship, Participation and RoleLink classes (the so-called "arrow" classes), the clone name SHALL use the formal name, with only suffixes added to provide disambiguation within a model.
3. Classes cloned from RIM classes other than ActRelationship, Participation and RoleLink may be named with a "business name" appropriate to the domain (remembering that the semantic meaning of the class must come from the controlling codes and the RIM definitions).

Naming derived attributes

1. The names of attributes in a derived information model shall be identical to the name of the RIM attribute from which the attribute is derived.

Naming derived associations

1. Formal names of associations are based on the controlling attributes, as follows:
   • names for associations involving the “arrow” classes (ActRelationship, Participation and RoleLink) are based on the constraint assigned to their constrained typeCode;
   • names for associations between clones of Entity and Role are based on the constraint assigned to the classCode of the Role clone involved;
   • any of the association names above may also include the name of the clone at the other end of the association; and
   • all other associations must use their RIM-assigned association role name, which in most cases is the name of the clone at the other end of the association.
2. All associations in a derived information model must be named with the formal name for that association, with only suffixes added to provide disambiguation within a model.

Cardinality constraints

Cardinality constraints apply only to attributes and associations. Every attribute or association element in a model has an explicit or implicit cardinality that expresses the number of times an attribute or association may appear in a derived model or model instance. Since associations in HL7 information models are directional, the cardinality constraint of an association is equal to its destination multiplicity, i.e. the minimum and maximum number of times instances of the target class of the association may be referenced.

When deriving a model both the minimum and maximum cardinality for a particular derived element may be constrained in a way that narrows the range of possible occurrences. Thus, either minimum or maximum values of the derived cardinality range may be set to a new value within the closed range defined by the minimum and maximum values in the source range. This is subject to two the further constraint rule that the minimum cardinality of the derived range must be less than or equal to the maximum cardinality of that range.

Type constraints

Type constraints apply to attributes, classes, CMET references, and Choices. Each of these model elements has a type explicitly or implicitly derived from information in the model specification.

• The type of a class can be determined either from the classCode or typeCode attribute of the class.
• The type of a CMET reference is determined by its name and "attribution" level.
• The type of an attribute is the data type declared for that attribute in the model.
• The type of a Choice of classes is determined by the set of classes in the Choice

Type constraints are constraints on the type of a model element. The constraint rules for classes are governed by the constraints on the vocabulary specification of its typeCode or classCode, and are not elaborated further.

Data Type Derivation Constraints

Each attribute classes in the base model is assigned a data type. When a class is cloned, the the attributes of that class in the derived model may keep the same data type that it had in the source class or may be constrained by making a valid type substitution to one of the allowable types specified in the Data Types Model bound to the base model. This document will not attempt to summarize or list the valid substitution patterns.

Common Message Element Types (CMETs)

CMET substitution - When a model is being derived, a CMET may be substituted for a class or a class clone, provided that:

• The CMET in the clone is based on either the same class as the base class being substituted or on a sub-type of that class,
• The values for the structural codes for the CMET fall within the vocabulary constraint specified for those attributes in the base class,
• That the body of the CMET that is substituted uses the constraint rules described here for the model being derived.

CMET constraint hierarchy - When a model is derived, the CMETs within that model may be further constrained along the defined restriction hierarchy for CMETs. The hierarchy is based on a general to specific refinement. The hierarchy is determined by the "attribution levels" of the CMETs, as defined in the CMET Normative Standards. The derived CMET must be at the same or a lower level of attribution than was the source CMET.

Choice element constraints

An HL7 v3 static model may contain a Choice element in the model. The Choice element is treated as if it were a class itself. The Choice element contains a finite number of other classes. If model X contains a Choice element and if model Y is derived from of model X, then model Y may contain a simplification of the Choice according to the following rules.

• Y may eliminate an entire Choice element, and any associations with the Choice as source or target, provided that the result is still a complete model. and that no associations to the choice were "Required".
• Y may eliminate any class from a Choice element, and all associations with only that class as source or target, provided that at least one class remains in the Choice.
• Y may reduce a Choice to a single class, and then may substitute that class for the Choice in the model, retaining the Choice associations as associations for the class.

Vocabulary constraints

Vocabulary constraints limit the values that coded attributes may take on. (If an attribute is derived from a RIM attribute that has a Concept Domain constraint (Property:vocDomain) assigned, then it is a coded attribute.)

A simplified set of Vocabulary constraint rules during model derivation are:

• If an encoded attribute in the base class is constrained to a Concept Domain "A", the derived attribute may be constrained to:
  • Concept Domain "A"

  • A Concept Domain that "specializes" Concept Domain "A"

  • A Value Set that has a universal "context binding" to Concept Domain "A" or to a Concept Domain that "specializes" Concept Domain "A"

  • If Concept Domain "A" has no universal "context binding"
    • A Value Set that includes the concepts defined by Concept Domain "A" (model binding).

    • A single coded concept from a code system (fixed value assertion), where the coded concept is a valid member of the concepts defined by Concept Domain "A"
• If an encoded attribute in the base class is constrained to Value Set "B", the derived attribute may be constrained to:
  • Value Set "B"

  • A Value Set based on the same code system as Value Set "B" and whose content is a sub-set of the content of Value Set "B"

  • A single coded concept that is a member of Value Set "B" (fixed value assertion)
• If an encoded attribute in the base class is constrained to a single coded concept, the derived attribute must be constrained to the same coded concept.

Other value constraints

These constraints are those that limit the value for an attribute in ways not covered above. These are the assertion of a default value and the declaration that an attribute has a fixed value.

Default value may be declared for an attribute. The default is a single value for that attribute that will be asserted for an instance that does not contain the attribute. The default value may be any value that is valid for the data type and, if applicable, for the vocabulary constraint on that attribute. Once a default is assigned to an attribute, a different default cannot be assigned for the same attribute in a derived model.

Fixed value - In an information model an attribute of a class may be assigned a fixed value. The fixed value may be any value that is valid for the data type and, if applicable, for the vocabulary constraint for that attribute. Once a fixed value is assigned to an attribute, a different fixed value cannot be assigned for the same attribute in a derived model.

Content Guidelines

1. Some rule
   1. Rationale: Some reason
2. Some other rule
   1. Rationale: Some other reason

Publishing Representation(s)

1. The primary distribution of these information model artifacts SHALL be in the form of an XML file formatted according to the HL7 Model Interchange Format (MIF schemas).
   • (See Artifact Technology - Rationale above for rationale.)
2. Near-term (2011-12) supplemental distribution formats from the HL7 RMIM Designer:
   1. Visio (*.vsd) file for the artifact

   2. RMIM Designer XML file for the artifact

   3. Graphical representation (.png)

   • Rationale: Support existing tool base.
3. Ballot representation will be in HTML form derived from the MIF file and a Publication Database by V3 Publishing and the V3 Generator to include:
   1. Defining properties and a "walk-through" of the model as defined in a Publication Database

   2. Graphical Representation in PNG

Publishing Constraints

1. Some rule
   1. Rationale: Some reason
2. Some other rule
   1. Rationale: Some other reason

Tooling Considerations

The following defines the ideal tool for use in creating these artifacts. The rationale for these elements is expressed in the "Rationale" sub-section of the "Artifact Technology" section above.

Ideal model creation tool for this artifact

Would be a UML Modeling tool that has been customized to:

1. Capture and represent the HL7-defined properties that are applicable to this model

2. Able to "read" and "write" the content in MIF format
   1. Including the graphic layout of the model

3. Able to define and document:
   1. Entry Points

   2. Common model (CMET) references

   3. Other model references, and

   4. "Stub" classes

4. Able to enforce derivation constraints on the model using the RIM and Vocabulary Model (from MIF files) to configure these constraints dynamically

5. Able to configure the tool user interface using the RIM, Vocabulary Model and Interface Model (CMET file), provided as MIF files) to provide selections that are proper constraints and/or content from, these key derivation sources.

6. Able to represent the graphic expressing on model classes using the HL7 Static Model BNF Grammar

Development Process Considerations

Development guidance and guidelines for these artifacts can be found in the Version 3 Publishing Facilitators Guide that is published as a part of every ballot. This document includes an overview of the material that must be created for a ballot as well as specific notes related to specific to domain information models (listed under DMIMs) and serializable information models (listed under RMIMs).

Governance Process Considerations

1. Governance Process name - Some process description
   1. Rationale: Some rationale
2. Another Governance Process name - Process description
   1. Rationale: Some other rationale

Issues

• Some issue
• Some other issue