Template Functional Requirements

HL7 V3 Templates maintain a set of functional requirements. What is the list of functional requirements required of Templates for use in HL7?

Disclaimer

---

The purpose of this work - working through the joint CEN and openEHR Archetype Requirements in detail - is to provide the basis of understanding for the requirements of HL7 Templates only. This work is NOT intended to be the formal HL7 Templates requirements document.

Acknowledgements

---

The specification of HL7 templates defined here has been produced under work program of the HL7 Templates Special Interest Group. It has been greatly influenced by the work contained within the CEN 13606-2:2005 (Annex A) draft standard which defines formal requirements for 'archetype' representation. Representatives of the CEN an openEHR standards working group have supplied this in the interest of harmonisation of CEN and HL7 standards work in the templates area. Many thanks to Dr Dipak Kalra for his support of this process and continuing engagement with HL7, CEN, and openEHR harmonisation work.

HL7 Template Metadata

Identification Metadata - Required

---

templateID

A globally unique, non-semantic, identifier for the Template. Within the context of HL7, a templateID should take the form of an ISO Object Identifier (OID) or an HL7 Artifact ID. This is the primary identifier for all Templates.

templateName

A free text natural language name identifying the Template. It is anticipated that there will be far too many templates to be able to assign a unique mnemonic or meaningful name to all of them. This is the secondary identifier for all Templates. (Refer to templateCodedTerm.)

originatingAuthorEntityID

A globally unique non-semantic identifier for the original author of the Template.

templateIntention

A free text natural language description of the intent and scope of the Template. The purpose is to provide the author’s initial intent for the Template.

NOTE: A change to the semantic meaning or intent of a Template will constitute a new Template, not a new version of the Template.

templateVersion

The version identifier for the Template. The ability to determine the correct version of a Template is essential to its identification.

==== templateReferenceModelID ==== The globally unique identifier (ISO OID or HL7 Artifact ID) of the reference model against which the Template was developed. The underlying reference model may be A DIM, LIM, or Profile or Template.

==== templateRepositoryIdentifier ==== The identifier of the repository where the Template is located. This is a required metadata item since the core functional purpose of a Template is reuse, and things in general are much harder to reuse when they cannot be easily located.

Open Issue: What form should this identifier take?

==== templateRegistrationAuthority ==== The identifier of the registration authority (organization, institution, committee, or individual ) for the Template.

Open Issues: What are registration rules? What is the relationship between the repository and registration? What is the purpose of regsistration?

Identification Metadata - Optional

---

==== templateCodedTerm ==== The coded concept that uniquely represents the templateName within a given code system. A concept code can be assigned to an entire Template, providing it with a language independent method of secondary indentification. This can be used in conjunction with the templateName to convey the intended purpose and use of the template. (Refer to templateName.) The same templateCodedTerm and templateName may be used in multiple Templates.

Description Metadata – Required

---

==== descriptionLanguage ==== The natural language in which the Template is represented.

==== templateDescription ==== A free text natural language description of the intent and scope of the Template. The purpose is to provide the author’s initial intent for the Template.

Description Metadata – Optional

---

==== implementationFormat ==== The preferred format that the Template should be implemented in from an ITS perspective. Implementation formats other than that recommended(if any) are not deemed suitable for this Template by the publishingAuthority. Other implementation formats are possible, but it is the responsibility of the translator to make the tralation to the new format, not that of the publishingAuthority.

==== evidenceSource ==== A description, reference or link to the published medical knowledge that was used in the definition of this Template.

==== detailedDescription ==== A detailed explanation of the purpose of this Template, including features of intrest. This may include an indication of the intended user group for which this definition is intended.

==== cautionPoints ==== A formal statement regarding when this Template should not be used, or may be used erroneously. To define roles where the Template should not be used, or should be used with care. This field is used to expand in detail on the templateIntention.

Publication Metadata – Required

---

==== publicationStatus ==== The current publication status for the template.

• Development
• Test
• Private
• Public
• Preferred
• Former
• Deprecated

==== publicationStatusChangeDate ==== The date that the current value for publicationStatus was applied of the Template.

==== publisher ==== The name of the author(s) institutional affiliations and contact infomation for the creators of the Template.

==== publishingAuthority ==== The autoritative body who has reviewed the Template for clinical accuracy and relevance, and autorized it for publication.

==== revisionHistory ==== The free text description describing the changes in this version of the Template as compared to the previous version. Since Template versions are built off of previous versions, the net effect of this field is to function as a comprehensive historical reference of the Template.

Publication Metadata – Optional

---

==== effectiveDate ==== The date after which the Template can be considered for use. Use of the Template prior to this date would be considered an invalid use of the Template.

==== expirationDate ==== The date at which the clincal concept represented by this Template becomes stale, and should be reviewed for clinical relevance and accuracy. Use of the Template after this date would be considered venturesome.

Template Node Constraints

---

templateNode

---

Explicitly defines a node in the template constraint definition. Template nodes are organised in a hierarchial structure. The top level constraint node is known as the 'root template node' or the 'template'.

templateNodeId

A globally unique, non-semantic, identifier for the template node. Within the context of HL7, a templateNodeID should take the form of an ISO Object Identifier (OID) or an HL7 Artifact ID.

templateNodeReferenceModelID

The globally unique identifier (ISO OID or HL7 Artifact ID) of the reference model against which the Template was developed. The underlying reference model may be A DIM, LIM, or Profile or Template

templateNodeReference

---

References a template node that can be used in the template node hierarchy. This may be referring to a template root node or a template node within an explicit template definition.

inclusionRationale

Annotation as to the rationale for inclusion of this template node reference at this point in the hierarchy.

templateReferenceId

A node reference may refer to another template, this identifer (ISO OID or HL7 Artifact ID) specifies the relevant template. A node reference may refer to another template node contained within a template, this identifier (ISO OID or HL7 Artifact ID) specifies the relevant containing template.

templateNodeReferenceId

A node reference may refer to a pre-existing template node by it's unique template node identifier (ISO OID or HL7 Artifact ID) The template node may be within the current template, or an external reference to a node within another template.

templateNodeConstraines

---

Constrains allowed nodes based on the attributes of a template node definiton.

inclusionRationale

Annotation as to the rationale for inclusion of this template node constraint at this point in the hierarchy.

constraintStatement

Statement of the constraints placed on template nodes that are allowed to be included at this point in the template node hierarchy.

templateNodeChoice

---

A node choice allows the selection of one of a set of possible choices, this may be an explicit templateNode, referrence templateNodeReference or constrained node templateNodeConstrained.

---

Instantiation Constraint Rules

---

in progress

Constraint rules on an archetype node must identify the expression formalism employed.

Constraint cardinality of an archetype node must be defined. (is this HL7 DT & RIM?)

Constraint rules may be specified to govern allowed archetype node instance creation.

Constraints may be expressed as logical conditions referencing operating environment, or pre-existing archetype nodes in the instance hierarchy.

Constraint rules may be expressed as inclusion or exclusion criteria. That is rule-in or rule-out instantiation of specified archetype node.

codedTermBinding

---

in progress

Every archetype node must be associated with at least one clinical term. (can all nodes be bound to clinical concepts?)

Each archetype node may be associated with additional clincal concepts, terms, or synonyms.

Coded term (mapping?) purpose must be labelled: - prinicpal concept - code system translation - language translation - synonym

Any referenced coded term must include code, code system (OID), and display name text.

Reference Model Association Constraints

---

in progress

Name of the association for which this archetype node was ideally fashioned may be defined.

Label of type of association (code) for which this archetype node was ideally fashioned may be defined.

Cardinality constraints may be defined on instantiation of associations.

Other constraints or rules may be specified in a desired expression formalism. (including plain text? allowed formalism?)

Reference Model Attribute Constraints

---

in progress

Name of the attribute for which this archetype node was ideally fashioned may be defined.

Label of type of attribute for which this archetype node was ideally fashioned may be defined.

Cardinality constraints may be defined on instantiation of attributes.

Multiple instances can be specified as unordered list, ordered list or a unique instance set. (need to refer to HL7 collections)

Constraints may be made on leaf attributes.

Other constraints or rules may be specified in a desired expression formalism. (including plain text? allowed formalism?)

Constraints may be made on data value leaf nodes. Data-type value restriction.

HL7 Template Data Value Constraints

structuralAttributeConstraints

---

It must be possible to specify constraints and rules for the Structural Attributes within the Reference Information Model.

- in process

dataValueConstraints

---

It must be possible to specify data value constraint information, including:

• Null and null flavor values as well as an optional reason to specify a null flavor value.

• If the constraint or rule specifies inclusion or exclusion criteria.

• The formalism (including version) in which this constraint specification is represented.

• The intended fixed (prescribed) value for conforming instances.

• The intended default value for conforming instances.

• A list of permitted candidate values for conforming instances (i.e. to be a subset of those vales legally permissible in the underlying Reference Model.)

Quantity data types must be able to specify

---

==== inclusiveQuantity ==== A value range where the value(s) for conforming instances must be inclusive;

==== exclusiveQuantity ==== A value range where the value(s) for conforming instances must be exclusive;

==== inclusiveCritical ==== A range within which values are considered to be clinically exceptional or critical.

==== exclusiveCritical ==== A range ouside of which values are considered to be clinically exceptional or critical.

Date data types must be able to specify

---

==== inclusiveDateValueRange ==== A value range where the value(s) for conforming instances must be inclusive;

==== exclusiveDateValueRange ==== A value range where the value(s) for conforming instances must be exclusive;

==== dataValueUnits ==== The intended measurement units for conforming instances.

Textual Data Types

---

==== regularExpression ==== A Regular Expression pattern defining the range of possible values for a String.

codingScheme

---

The intended coding scheme to be used for conforming instances for the textual data.

Logic Operators

---

Constraint rules might be expressed using logical operators, and may include reference to environment parameters such as the current time or location or participants, or be related to the (preexisting) values other nodes in the instance hierarchy. Relative constraints may be nested, and include logical or set operators in order to represent compound rules.

• Logical operators can be applied to a set of assertions to indicate which assertions in the set must be true or false. Example: (All | at least X | at most X | exactly X) of the assertions contained in this set must be (true | false).

Template Reference

---

The reference to a preexisting value must specify that instance precisely and unambiguously.

==== templateID ==== The Template identifier (templateID) for the Template being referenced

The occurrence in the instance hierarchy

• First
• Most Recent
• Any
• N ordered by Y (the nth set of instances ordered on y)
• highest value
• lowest value
• one or more instances within a definable time value

Template Assertions

Static assertions

---

• A template can constrain the cardinality of a clone’s association.
• A template can constrain the cardinality of a clone’s attribute.
• A template can constrain the allowable date/time values in a date/time field.
• A template can constrain any attribute value to be a subset of those values legally permissible in the specification being constrained.
• A template can constrain the range of allowable date/time values for attributes valued by date/time data types.
• A template can constrain the range of allowable code values for attributes valued by terminology concepts.
• A template can constrain the range of allowable numbers for attributes valued by numbers.
• A template can express a regular expression constraint on attributes valued by strings.
• A template can constrain any data type component, including recursively-nested components.
• A template can constrain the range of allowable values of a clone’s attribute.
• All additional constraints that can be expressed in a normative specification (including all the columns in an HMD) can be further constrained in a template.

Co-occurrence Assertions

---

• The value of one field can be constrained based on the value of another field.
  Example: If fieldOne is “X”, then fieldTwo’s value must be “A”.
  

• Chronological assertions can constrain the date/time value of one field based on the date/time of another field.
  Example: The start time for fieldOne is (earlier | later | equal to) the start time of fieldTwo.

• Numeric comparison assertions can constrain the numeric value of one field based on the value of another field.
  Example: The value of fieldOne is (equal to | less than | greater than) the value of fieldTwo.

• Numeric operation assertions can constrain the numeric value of one field based on a numeric operator applied to the value of another field or constant.
  Example: The value of fieldOne is (equal to | less than | greater than) the value of fieldTwo (plus 7 | divided by 27).

• String comparison assertions can constrain the string value of one field based on the value of another field.
  Example: The string value of fieldOne is contained in the value of fieldTwo.

• Any constraint a template and constituent archetypes can make can be made dependent on the value expressed in one or more other fields. For instance, in addition to constraining the cardinality of an association, a template and constituent archetypes can constrain the cardinality based on the value in a particular field.
  Example: If ((fieldOne is “X” or “Y”) OR (fieldTwo is “ABC”)) then ((a nested act relationship under Observation is required) AND (fieldThree in the nested act has a value of “A” or “B” or “C”) AND (fieldThree in the nested act cannot be NULL)).

Containment Assertions

---

• Data descendant assertions can constrain allowable depth at which one component is nested within another component.
  Example: The vital-signs section must be (a direct child of | some descendant of | less than a depth of X from) the physical-exam section.

• Items in a template and constituent archetypes can be “ordered” or “unordered”. In an ordered template and archetype, the order of the stated assertions is important. In an unordered template and archetype, the order is not important.
  Example: Assertion One: There is a nested act under observationOne that has an observation.cd for “hemoglobin”. Assertion Two: There is a nested act under observationOne that has an observation.cd for “hematocrit. If the template and constituent archetypes are “ordered”, the “hemoglobin” must come before the “hematocrit”. If the template and constituent archetypes is “unordered” the “hemoglobin” can come before or after the “hematocrit”.