Template:SAIF Generic IM Constraints

Generic Content Constraints for SAIF Information models.
         Only the content appearing below in black font will appear in the inclusion.
Go to SAIF Artifact Definitions
These elements are intended to appear under the following section:

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.