This page has been created to gather the requirements for the definition of templates (canonical template format).
As a first draft this is the preliminary ballot content of Patient Care Provision Template Requirements.
Use of Templates in Care Provision
An HL7 template is a constraint on models based on the HL7 Reference Information Model (RIM). It expresses the data content needed in a specific clinical or administrative context.
In healthcare there are prescribed patterns by which, for example, multiple observations may be combined to describe selected, gross observations. Some observations may be simple, such as the single lab result (e.g. potassium in blood is 4.4 mEq/L) or the blood pressure concept, which involves a set of expected observations (i.e., systolic, diastolic, patient position, method, etc.). Other more elaborate diagnostic procedures may involve hundreds of related pieces of information, including anatomy, orientation, sequences of measurements, etc.
In HL7, more or less generic models exist; the Patient Care model, especially the Care Statements = Clinical Statement Pattern (CSP) is one of it. Templates provide a method of describing rules for combining and constraining HL7 v3 XML instances like a Patient Care message. Templates can be used for three purposes:
- To have a guideline to create (a fragment of) a Patient Care message instance
- To validate an instance whether it conforms to the specified template rules
- To have a guidance while processing a Patient Care message instance.
The last point should be considered carefully, because an instance must convey fully semantics even without knowing the underlying template.
Based on user need and preference, the template ideally is a structure that can be used as a building block and, once defined, can be re-used whenever appropriate.
Kinds of Patient Care templates
The Patient Care standard describes conformance requirements in terms of two general levels:
- Message root level templates: they define / refine the overall structure of a message starting from the Care Provision class, which templates are contained in the message and whether they are optional or required.
- Substructure level templates (patient, provider etc.)
- Clinical Statement level templates: impose the Clinical Statement Pattern of a Patient Care message; they define the constraints on the classes, class attributes, data types and class relationships.
Template Identifiers in instances
Template identifiers (templateId) are assigned at the Message root level and Clinical Statement level. When valued in an instance, the template identifier signals the imposition of a set of template-defined constraints. The value of this attribute, e.g.
<templateId root="2.16.840.1.1138188.8.131.52.3" />
provides a unique identifier for the template in question.
If a template is a specialization of another template, its first constraint indicates the more general template. The general template is not always required. In all cases where a more specific template conforms to a more general template, asserting the more specific template also implies conformance to the more general template.
Open and Closed Templates
In open templates, all of the features of the Patient Care based specification are allowed except as constrained by the templates. By contrast, a closed template specifies everything that is allowed and nothing further may be included.
Open templates allow HL7 implementers to develop additional content not constrained within the template. HL7 encourages implementers to bring their use cases forward as candidate requirements to be formalized in a subsequent version of the standard to maximize the use of shared semantics.
In general, Patient Care defines open templates only.
Template metadata is mainly defined in the “Business Requirements for Template Registries”. In order to support template registries and to allow the appropriate use of templates, the following metadata is associated with each template.
A mandatory globally unique, non-semantic, identifier for the template as the primary identifier.
A required name for the template as a secondary identifier. Please note that there is no guarantee that the name is globally unique.
The mandatory 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.
The optional date at which the 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.
The mandatory status of the template. According to the Business Requirements for Template Registries the following status codes of a template shall be supported.
|draft||Template under development (nascent). Metadata and template may be incomplete. Entered primarily to encourage other users to be aware of ongoing process.|
|active||Template has been published by the custodian organization and deemed fit for use. May have associated adoption and annotation metadata|
|retired||Template retired: No longer fit for use. Information available for historical reference.|
|inactive||Template never recommended for use. For example, rejected, withdrawn or found another template fit for use of the one under development. Will not have associated adoption metadata.|
|rejected||Template is rejected|
|cancelled||Template is withdrawn|
|update||Template under Update (adoption metadata): adopter adds adoption metadata and/or grouping metadata: these are the only actions an adopter organization can perform. The template(s) in the “under update (adoption metadata)” status are unavailable for any other status or metadata changes until the “under update/adoption metadata” action has been completed.|
|pending||Template is in pre-publication review: the template is complete, pending appropriate review. Entered primarily to encourage other users to be aware of and/or participate in the review process. The custodian organization has not given it an “Active” status (i.e. it has not been published); and it may still be rejected (transitioned to an inactive status). E.g. the template may be under ballot by an SDO.|
|review||Template is in Review: a post-publication state; may result in a new version or a retirement or no change at all. A new version is one that adds clarity but not new intent; the version number is incremented by one, but the identifier is unchanged. A retirement is a template that is no longer fit for purpose, and which may be replaced by a different a template with a different identifier, which is linked to the retired template.|
The optional human readable display name for the template for orientation purposes. This is not intended for machine processing.
The optional human readable version label for the template to be able to determine the correct version of a template. This is not intended for machine processing.
An optional 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. A description may be present in different languages.
An optional context of the template, i.e. where in an XML instance the template rules are considered to applied to. From a practical viewpoint templates may have no context. In this case the template is not “exposed” for external use, but rather used for internal inclusion in other templates. If the template is intended to be published for external purposes, it shall have a context. Typically there are three types of context specifications.
sibling node context
The template rules apply to all sibling elements and descendent nodes in the instance.
parent node context
The template rules apply to the siblings of the parent node and all descendent nodes in the instance.
pathname specified context
A pathname (making use of XPath expressions) is specified, which allows to activate templates in an instance without the need to have template id elements in an instance.
The item is used as an identification mechanism when it comes to error messages by derived validation scripts. For example if each constraint has a (unique) number, it may be used to precede every error message.
Templates may have zero to many example fragments to illustrate valid instances. In addition, each class attribute definition may have also an example fragment.
Changes to the Template that do not change the semantics or intention of the template will constitute a new version of the Template being created. This means that the id of the former template remains the same and the @effectiveDate is changed to the date when the new version of the template was created.
Any change to the semantic meaning of the template will constitute the creation of a new template. This means that a new template will get a new @id.
Expressing Constraints in Templates
Constraints expressed in templates may determine
- The data type or a data type flavor
- The cardinality
- The conformance, e.g. if data may be absent (nullFlavor)
- Vocabulary bindings and coding strengths
- Possible fixed values
- Additional properties such as units (measurements), ranges, fraction digits
of a class attribute. In general this means to determine the properties of an XML element or an XML attribute. In addition, containment relationship and co-occurances of items may also be determined.
Data Type Constraints
The data type of a class attribute is simply determined by specifying a data type name or a data type flavor name.
Note that the constraint shall be equal to or a valid demotion of the corresponding data type of the underlying model (if present).
Although not present in HL7 Data Types Release 1 or 1.1, data type flavors are the preferred way in templates to constraint data types of class attributes.
Allowed Data Absent Reasons (Null Flavors)
In cases where data may be absent, i.e. non-mandatory attributes, indicated with a @nullFlavor in an instance, the list of possible codes for the reason of absent data may be restricted.
This allows to express the intended fixed (prescribed) value for conforming instances.
In practice so far no use case is known for specifying default values in a template.
List of Allowed Values
In practice so far no use case is known for specifying a list of allowed values in a template. This makes sense for ordinal values only anyway.
For integers this can be done by specifying minimum and maximum included values rater than the list of valid integers. For codes one should use value sets.
A Regular Expression pattern defining the range of possible values for a string. In practice so far no use case is known for specifying regular expressions as a textual restriction in a template.
The intended coding scheme to be used for conforming instances for the textual data.
In practice so far no use case is known for specifying coding schemes as a textual restriction in a template.
The cardinality indicator specifies the allowable occurrences within a message instance. The cardinality indicators are interpreted with the following format “m…n” where m represents the least and n the most:
- 0..1 zero or one
- 1..1 exactly one
- 1..* at least one
- 0..* zero or more
- 1..n at least one and not more than n
In some implementation guides conformance verbs as SHALL, SHOULD, MAY etc. are used. This is not handled consistently across several organizations (e.g., HL7, IHE, see also [Consolidating CDA Templates]). Once, conformance indicators are unified the can be incorporated in this document as well.
In this guide conformance verbs are used for vocabulary constraints (see following section) but not for templates as a whole or for template elements.
HL7 conformance indications are used instead. The following table gives an overview of mandatory items, the cardinality, conformance and whether data may be absent (nullFlavor).
|Mandatory||Conformance||Minimum Cardinality||Null ok?||Comment|
|M||R||1||No||Shall be present and valued in a message|
|(not mandatory)||R||0||Yes||If no information is available, just don't send it|
The attribute is mandatory, i.e. a valid value shall be provided and no null value is allowed. The minimum cardinality is at least 1. This also includes that if the sender has no valid value for such an attribute, the message cannot be sent. It is indicated as “M” in the conformance column of the attribute table, a shorthand for “mandatory” with required conformance.
The attribute is required, i.e. a valid value should be provided or if missing a null value is allowed if its minimum cardinality is 1, or may be omitted if its minimum cardinality is zero.
In messages, the element must be communicated if its minimum cardinality is one. In the case where the element is not mandatory, it may be communicated with a null value. Note that any element declared to be "Mandatory" must also be "Required" and have a minimum cardinality of one. If the minimum cardinality is zero, and the element is "Required", conforming applications need not send the element if data does not exist. For required elements, conforming applications must demonstrate their ability to provide and communicate not null values. Receiving applications must demonstrate their ability to receive and process (eg. Store, display to users) not null values for required elements.
It is indicated as “R” in the conformance column of the class attribute table.
The attribute is truly optional, i.e. a valid value may be provided or if missing may be omitted.
It is indicated as “O” in the class attribute table, a shorthand for an unspecified conformance with a minimum cardinality of zero.
This usage has an associated condition predicate. It is denoted in the following format:
where a..b is the cardinality, conf denotes the conformance and condition is the condition, in human language or formalized in some constraint language. Please note that all predicates shall be mutually exclusive.
If the predicate is satisfied then
- a conformant sending application must always send the element
- a conformant receiving application must process or ignore data in the element; it may raise an error if the element is not present.
If the predicate is not satisfied then
- a conformant sending application must not send the element.
- a conformant receiving application must not raise an error if the condition predicate is false and the element is not present, though it may raise an error if the element is present.
A conditional attribute is indicated as “C” in the class attribute table, followed immediately by the condition predicate table.
This indicates that an attribute has a fixed value. It fixed value shall appear in an XML instance.
It is indicated as “F” in the class attribute table, a shorthand for a mandatory element with required conformance with a fixed value. The cardinality should be 1..1.
This indicates that an attribute is not used. In principle, it is not part of an XML instance but is not rejected by validation mechanisms if present and a receiver should not raise an error when he received the element.
It is indicated as “X” in the class attribute table.
The attribute is not permitted, not part of an XML instance, rejected by validation mechanisms if found and should be rejected by receiver (raising an error).
It is indicated as “NP” in the class attribute table. There is no cardinality specified.
The templates in this document use terms from several code systems. These vocabularies are defined in various supporting specifications and may be maintained by other bodies, as is the case for the LOINC® and SNOMED CT® vocabularies.
Note that value-set identifiers, e.g., ValueSet 2.16.840.1.1138184.108.40.206 HL7ObservationInterpretation DYNAMIC, do not appear in messages/documents; they tie the conformance requirements of an implementation guide to the appropriate code system for validation.
Dynamic vs static binding
Value-set bindings adhere to HL7 Vocabulary Working Group best practices, and include both a conformance indicator and an indication of DYNAMIC vs. STATIC binding.
- Value-set constraints can be STATIC, meaning that they are bound to a specified version (date) of a value set,
- or DYNAMIC, meaning that they are bound to the most current version of the value set.
XML attributes are denoted by a preceding @ and have cardinalities 0..1 (optional) or 1..1 (required) only. If an attribute is prohibited (may not be present), its conformance is set to NP.
HL7 Data Types Release 1 requires the @codeSystem attribute unless the underlying data type is “Coded Simple” or “CS”, in which case it is prohibited. The @displayName and the @codeSystemName are optional, but recommended, in all cases.
The containment relationship constraints between a specific structure (context) in an XML instance and sub-structures in that context (child elements).
They may be indirect, meaning that where a structure asserts containment of a substructure, that substructure can either be a direct child or a further descendent of that structure, or be direct, meaning that the contained substructure shall be a direct child of the structure.
Co-occurance means the presence of some data depending on the presence or value of some other data. There are intra-instantial co-occurances where a condition applies to one single instance, and extra-instantial co-occurances where the presence of data in an instance is influenced by external factors (outside the very same instance).
In thsi specification, only intra-instantial co-occurances are handled.
Originator Responsibilities: General Case
An originator can apply a templateId if there is a desire to assert conformance with a particular template.
In the most general forms of CDA exchange, an originator need not apply a templateId for every template that an object in an instance document conforms to. The implementation guide (IG) shall assert whenever templateIds are required for conformance.
Recipient Responsibilities: General Case
A recipient may reject an instance that does not contain a particular templateId (e.g., a recipient looking to receive only Procedure Note documents can reject an instance without the appropriate templateId).
A recipient may process objects in an instance document that do not contain a templateId (e.g., a recipient can process entries that contain Observation acts within a Problems section, even if the entries do not have templateIds).