Naming Rules For HL7 Static Information Models

Background

Early on, HL7 decided to represent its information models as UML models. Technically, the RIM, DMIMs, RMIMs, and HMDs are UML static information models, in which the elements of these models have additional HL7-specific properties.

Although there are UML conventions for the naming of the elements in these models, there are no hard and fast rules. Therefore, in order to provide consistency across the HL7-developed information model, the Methodology and Modeling Committee adopted a set of naming rules to be used.

Uniqueness Requirements

In developing these rules, HL7 needed to recognize the following requirements imposed by UML:

• 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 Reference Information Model (RIM) is a highly abstract model that permits more specific models to be derived from it by constraining the values of the "classCode" and "typeCode" attributes found in several of its "back-bone" classes. The intent of this process is that the semantic meaning of any given derived class (clone) should be determined solely by the value of these structural attributes in combination with the definition of the RIM class from which the class is derived. Thus, the requirement is that the name of a class or association should not be relied on to understand the semantic meaning of the class. The meaning must come from the structural codes and the RIM definitions.

Naming style

The first step in defining these rules was to establish the rules for name style – how these names will be represented. Among these rules are:

• 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 Message Element Types (CMETs) in which the opening characters are 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. This convention was adopted to assure that CMET names, which are included in other information models, will not collide with any other names in those models.
• 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 structural attributes, the names of those classes may be disambiguated by adding numeric or other suffixes.

Governing Principles

The following governing principles were adopted to manage this process, in many cases these are rules. The first such rule for classes and associations is a requirement for HL7 to define an algorithm for deriving formal names from model constraints. Specifics of this algorithm are documented as download document Formal Naming Algorithms under the Tooling Documentation Project on the HL7 G-forge site.

Naming class clones

1. HL7 (through harmonization) shall specify an algorithm that defines a unique formal name for any clone of a RIM class where the class is "defined" by a type code or a class code (plus mood and determiner code, if applicable). (Specifically, this applies to classes clones from members of the Act, Role and Entity generalization hierarchies, and to classes cloned from ActRelationship, Participation and RoleLink.
2. The formal names for class clones shall be:
   • based upon the constrained value of their classCode, in the case of clones of Act, Role and Entity, with moodCode and determinerCode providing further naming qualifications for Act and Entity, respectively; or
   • based upon the constrained value of their typeCode, in the case of clones of ActRelationship, Participation or RoleLink; or the
   • the RIM class name, for clones of any other RIM class.
3. For classes cloned from the ActRelationship, Participation and RoleLink classes (the so-called "arrow" classes), the clone name must be the formal name for that clone, with only suffixes added to provide disambiguation within a model.
4. Classes cloned from RIM classes other than ActRelationship, Participation and RoleLink may be named with a "business name" appropriate to the domain, but recognizing that the semantic meaning of the class must come from the structural 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. HL7 (through harmonization) shall specify an algorithm that defines a unique formal name for any clone of a RIM association (instance relationship).
2. Formal names of associations shall be based on the structural attribute constraints in the model, as follows:
   • names for associations involving the “arrow” classes (ActRerlationship, Participation and RoleLink) shall be based on the constraint assigned to their typeCode in the model;
   • names for associations between clones of Entity and Role shall be 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.
3. 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.

HL7 Graphic Conventions for Derived Information Models

Although HL7's graphic conventions for representing derived models (RMIMs) are not strictly part of the naming rules, they reflect other rules imposed on the information model designers that do interact with the names to affect one's understanding of models. This section looks at the sub-set of those conventions that reflects class and association names.

The figure below represents a small "RMIM design" presented using HL7's graphic conventions with annotations (numbered boxes and colored arrows) added.

The diagram shows five regular (rectangular) classes from the backbone, two "arrow" classes" and one class from outside the backbone (deep blue). The conventions of interest are:

• All "non-arrow" classes have their class name as their primary label (annotations 1 & 2)
• The "arrow" classes have their association name (from the perspective of the starting class) as their primary label (annotation 1A)
• The class names of the "non-arrow" classes may be either their "formal name" (annotation 1) or a business name (annotation 2)
• Association names from any class to a "non-arrow" class are displayed adjacent to the class at the end of the association. This name must be the formal name which may be either the name of the ending class (annotation 3) or an alternate (annotation 4).
• Association names from any class to an "arrow" class are displayed as the primary label of the "arrow" class (annotation 1A).

For comparison, the following figure shows the same model diagramed using UML conventions.

In this circumstance, the figure shows the class name for all classes and associations, but it fails to illustrate:

• The associative function of the "arrow classes"
• The cardinality constraints imposed on attributes
• The appearance constraints (mandatory and required) imposed on attributes..
• Vocabulary domain constraints applied to classCode, typeCode and moodCode values which establish the essential semantic meaning of each class
• The coding strength constraint applied to coded attributes