Static Model Quality Checklist

Introduction

This checklist came out of the Sept, 2009 WGM (Tuesday Q2) as a mechanism to help ensure that "good practices" are followed by HL7 modelers. It will likely tie into the ARB's "Quality Criteria" initiative. The initial list came out of the WGM quarter, however others are encouraged to supplement it. We will schedule a peer review to have the criteria formally adopted.

The list is broken into "general" guidelines and "UV-specific" guidelines. The former apply to all models (including those created by affiliates and implementers). The latter only apply to HL7 UV specifications and tend to be focused on ensuring the appropriate level of "international" and "general, broad applicability"

Note that the list is ordered as the topics cam up during brain-storming. If someone wants to organize it better, go for it :>

QA Checklist

Following each checklist item, there is a pair of values describing the detection mechanism and the severity of the checklist item in the form: [x,x]

• Forms of detection: A - readily automated, S - Subjective assessment
• Compliance required for checklist item: A = Absolute requirement, B = would be Absolute for a standards but the intent is clear enough to permit ballot publication, G = Guideline

General

• Patterns
  • Use id pattern ( described here)
  • Use the “units” pattern where the possibility for discrete, non-UCUM units exists ( described here)
  • Clone Names must reflect the constraints of the class and its context within the model and must not imply semantics that cannot be inferred by looking at the structural attributes and other model constraints. This means the clone name shouldn’t contradict the constraints and also shouldn’t imply a level of detail not reflected by the constraints.
  • Check for abuse of Act.text [Look at the wiki to get appropriate wording]
  • If Observation.value is present, Observation.code should be mandatory (or at minimum have a constraint that it must be present if value is present).(Auto)
  • ??Context Conduction?? (Don’t do it if you don’t understand it)
  • The ContetConductionStyle for the model MUST be 'V'and if one or both of the ActRelationship"blockedConduction...." attributes is present it must be mandatory and have a fixed value (set orf values) assigned. [A
• Verify clone names and association names against MIF name constraint patterns. [A

• General
  • Avoid "deprecated" elements - classes, attributes, vocabulary constraints - when creating new designs or updating previous designs. [A,
  • Layout should be readable, focus on central concepts, avoid excessive dimensions, over-lapping classes, etc.
  • Pick up shadow rules from MnM List (Q4 2009) (need ref)
  • Deal with issue when serialization path first hits a choice through one of its classes. (tooling issue)
  • Assure that the meta data for the design (who responsible, approval status, when done, etc.) is complete (Mif header or PubDb xml) (Pub XML for now) (Currently cannot happen, automattically populated by PubDB)

• Vocabulary Constraints
  • Avoid use “Generic” Concept Domains like ActCode, ObservationValue, QueryParameterValue, etc. unless the design intends to be as "general" as the RIM [A
  • The concept domain specified for “code” should be consistent with the fixed value, concept domain or value set declared for “classCode”. [A
  • Before content can be “published” after balloting, the concept domains and value sets referenced MUST be approved by harmonization. (And if the name changes at harmonization, the model must reflect the change.). [A
  • When establishing a model binding, avoid using CWE coding strength with CV datatypes [todo: explain why]
  • When a non-immutable attribute is constrained to a concept domain, the concept domain shoudl be a defined specialization of the concept domain defined for the RIM attribute (possible exceptions may exist for RIM assigned domains of ObservationValue and QueryParameterValue) [A

• Attribute constraints
  • Use fixed values for immutable attributes where possible - single code or boolean value. Value set constraints should only used in the circumstance where it is reasonable and necessary for implementors to distinguish between individual members of the value set. [A
  • Where feasible, mark attributes as mandatory or required based on use-cases. I.e. Be careful about classes where all attributes are optional.
  • Attributes with fixed values must be required and mandatory. [A
  • Where elements have been constrained to mandatory and are not fixed values, rationale SHALL be supplied [A
  • For models intended for direct implementation, any element designated optional, rationale SHALL indicate why [A
  • Attributes with a datatype of ANY are constrainable to coded datatypes must define vocabulary bindings to be used in the event of such constraint [A
  • Where a default is declared in the RIM, it SHALL not be over-ridden. [A

• Descriptions
  • Include class-level and attribute-level descriptions on all non-fixed-value attributes. [A
  • Forbid invalid hl7-xhtml markup in descriptions. [A

• Unclassified and ToDo
  • Recognize that default values declared in models are guidance for implementers, they don’t eliminate the need to send the attribute
  • Todo: Guidance on negationInd, inversionInd and separatableInd
  • Todo: Harmonization proposal for uncertaintyCode to indicate the “implicit” default and/or set a default null flavor to NA?

UV-specific checklist

• Constrain all non-CS to Concept Domains, not Value Sets. [A

• Non-CS attributes should not reference value sets or fixed value codes unless the use of this value set or code in this model location has been endorsed by the Affiliates Council. [A

• Upper multiplicity should generally be set to 1 or * (one or many) [A,

• Don’t “over-constrain” models. For example, consider possible applicability to veterinary (non-human patients), multiple patient groups, etc.

• Where an attribute data type has been constrained from the RIM data type and the constraint is not a standard constraint (constraints of COLL jto SET, LIST, or BAG and EN to PN or ON), a rationale annotation explaining the constraint SHALL be recorded against the attribute. [A,

• Attributes constraining to LIST collection SHALL include in their definition the criteria by which ordering occurs. [A

Actions:

• (a) Publish in Facilitators Guide - who in Publishing?
• (b) Add to Generator using new facilities when done