This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Template Requirements

From HL7Wiki
Jump to navigation Jump to search

Related Links


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

HL7 Templates

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.113883." />

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

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.

statusCode Description
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.


CDA section level templates are often defined in sibling node context.

parent node context

The template rules apply to the siblings of the parent node and all descendent nodes in the instance.


CDA entry level templates are often defined in parent node context.

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.


Assume a recordTarget in an instance is considered to be unique for the payload. Then a template containing rules for the record target can be defined in the context of pathname hl7:recordTarget.


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.


A CDA “encounter” section level template defines the section code to be 46240-8 drawn from LOINC. Each constraint is uniquely identified by an identifier at or near the end of the constraint (e.g., CONF:7941).

Every error, warning or information that is raised during validation carries this constraint identifier.

The default is the template id.


Templates may have zero to many example fragments to illustrate valid instances. In addition, each class attribute definition may have also an example fragment.

Versioning aspects

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.


Examples of class attributes in table format, with different attribute names, data types (DT), cardinalitiy (Card), conformance (Conf) and description.

Table: Class Attributes with data type, cardinality, conformance and a description
Attribute DT Card Conf Description
repeatNumber INT 0..1 O Number of repetitions
value PQ 1..1 R The measurement as a physical quantity
code CE CNE 1..1 M The code of the observation

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).

Attribute Description Data type (flavor)
classCode Class code of the act CS
id Instance identifier II
effectiveTime A time stamp TS
value A measurement of a physical quantity PQ
lotNumber The lot number ST
repeatNumber a non-negative integer INT.NONNEG
date A timestamp that may be valued up to a day TS.DATE

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.

Example repeatNumber

A repeatNumber is a count, i.e. it is considered to be an integer which can be valued zero or more.

Ina template you can then

  1. define property minimum include of repeatNumber to be zero
  2. use data type INT.NONNEG instead of the unflavored INT

Both result in allowing repeatNumber to be valued with non-negative numbers only.

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.


The list of valid codes for a (required) coded observation (value) is drawn from ValueSet SomeValueSet. There is only one exceptional situation allowed to be expressed in an instance, i.e. that the value of the observation is not known.

In this case the list of valid @nullFlavor codes is restricted to be UNK only, i.e. the coded observation (value) shall be a code drawn from SomeValueSet or @nullFlavor = UNK.

Fixed Values

This allows to express the intended fixed (prescribed) value for conforming instances.

Structural Attributes

The most frequent use of fixed values are structural attributes. From a model perspective they are fixed and default to a single value (code). The cardinality of such structural attributes is handled to be either optional (like mostly in CDA) or required (as in V3 messages).

observation classCode="OBS" moodCode="EVN"

Default Values

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.

Quantity Ranges


Fractional Digits

Textual Restrictions


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
(not mandatory) R 1 Yes
(not mandatory) NP n/a No
(not mandatory) (unspecified) 0 Yes
Table: Overview of Conformance and Cardinality


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.


Class attribute code is 1..1 mandatory

Attribute DT Card Conf Description/Fixed value
code CE CNE 1..1 M The description of the code
Table: Class Attribute with data type, cardinality, conformance and a description


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:

Card Conf Predicate
a1..b1 conf1 If condition1
a2..b2 conf2 If condition2
... ... ... confn otherwise
Table: Condition Predicate Table

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.


The cardinality (of a class attribute) is 1..1 if number of gravidities is greater than zero or 0..1 otherwise

Card Conf Predicate
1..1 M If number of gravidities > 0
0..1 O otherwise
Table: Example Condition Predicate Table

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.

Not used

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.

Not present

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.

Vocabulary Conformance

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.113883.1.11.78 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.
Example: binding to a single code

A simplified constraint, used when the binding is to a single code, includes the meaning of the code, as follows.

Following a table with explicit XML attribute (data type CE) and binding to fixed code, codeSystem, etc.:

Attribute DT Card Conf Description/Fixed value
code CE CNE 1..1 M
  @code st 1..1 F 11450-4
  @codeSystem oid 1..1 F 2.16.840.1.113883.6.1
  @displayName st 0..1 F Problem List
  @codeSystemName st 0..1 F LOINC
Table: Example Class Attribute Table for a code


  1. SHALL contain exactly one [1..1] code/@code="11450-4" Problem List (CodeSystem: LOINC 2.16.840.1.113883.6.1)


The notation conveys the actual code (fixed 11450-4) in the required @code attribute, the optional code’s display name (“Problem List” if present), the required OID of the code system from which the code is drawn (fixed 2.16.840.1.113883.6.1), and the optional code system name (LOINC).

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.

XML example

The above example would be properly expressed as follows.


Examples: code with STATIC or DYNAMIC binding to a particular ValueSet

In the following example, class attributes are bound to ValueSets, STATIC and DYNAMIC.

Attribute DT Card Conf Description/Fixed value
confidentialityCode CE CWE 1..1 M ValueSet HL7BasicConfidentialityKind 2.16.840.1.113883.1.11.16926 STATIC 2010-04-21
languageCode CE CWE 1..1 R ValueSet Language 2.16.840.1.113883.1.11.11526 DYNAMIC
Table: Example Attribute Table


  1. SHALL contain exactly one [1..1] confidentialityCode which SHALL be selected from ValueSet HL7BasicConfidentialityKind 2.16.840.1.113883.1.11.16926 STATIC 2010-04-21.
  2. SHOULD contain exactly one [1..1] languageCode which SHALL be selected from ValueSet Language 2.16.840.1.113883.1.11.11526 DYNAMIC

The first notation binds mandatory confidentialityCode to value set HL7BasicConfidentialityKind (as of 2010-04-21), the second notation binds required languageCode to value set Language 2.16.840.1.113883.1.11.11526 (most recent version).

Containment Relationship

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.


A report about the first prenatal visit of a pregnant woman with historical findings recorded by an obstetrician or a midwife should contain an observation about the number of pregnancies so far (including the actual pregnancy), also known as “gravidity”.

Assume that the underlying model allows for clinical statements like an observation via a component relationship.

Attribute DT Card Conf Description/Fixed value
component 1..1 R Contains GravidityObservation template id 2.16.840.1.113883.
  @typeCode CS 1..1 F COMP
Table: Example Attribute Table


  1. SHALL contain exactly one [1..1] component such that it
    1. SHALL contain exactly one [1..1] @typeCode="COMP" (CodeSystem: HL7ActRelationshipType 2.16.840.1.113883.5.1002)
    2. SHALL contain exactly one [1..1] GravidityObservation (template id 2.16.840.1.113883.

Assume that the referenced template is an observation with a LOINC code 11996-6 (number of pregnancies, reported), then the above example could be properly expressed as follows.

<component typeCode="COMP">
   <observation classCode="OBS" moodCode="EVN">
       <templateId root="2.16.840.1.113883."/>
       <value xsi:type="INT" value="2"/>


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.

Example: Amnionicity and Chorionicity

Assume, that if the number of fetuses of a pregnant woman is more than 1 (multiple gestation), than an Amnionicity observation – number of fluid filled / (amniotic) sacs – and a Chorionicity observation– type of placentation – need to be reported.

Attribute DT Card Conf Description/Fixed value
component C Conditionally contains AmnionicityObservation template id 2.16.840.1.113883.
Card Conf Predicate
1..1 M If number of fetuses > 1
NP otherwise
  @typeCode CS 1..1 F COMP
component C Conditionally contains ChorionicityObservation template id 2.16.840.1.113883.
Card Conf Predicate
1..1 M If number of fetuses > 1
NP otherwise
  @typeCode CS 1..1 F COMP
Example: Immunization activity

An Immunization Activity can also include that a certain vaccination was not given (expressed as a negationInd/actNegationInd of the associated substance administration is valued “true”).

Assume that a business rule says that in this case an Immunization Refusal Reason shall be stated.


Attribute DT Card Conf Description/Fixed value
  @classCode CS 1..1 F SBADM
  @moodCode CS 1..1 F EVN
  @negationInd BL 0..1 O Refusal yes/no
  entryRelationship C Contains ImmunizationRefusalReason template id 2.16.840.1.113883.
Card Conf Predicate
1..1 M If @negationInd = true
0..1 O otherwise
    @typeCode 1..1 M RSON
Example APGAR panel
  • An APGAR score (assessment scale) is a simple and repeatable method to quickly and summarily assess the health of newborn children immediately after birth
  • The APGAR the sum comprises of five axes (Appearance, Pulse, Grimace, Activity, Respiration) each of it reported as 0, 1 or 2, resulting in valid sum scores values between 0 and 10. Normally the particular axes are not reported.
  • An APGAR panel contains exactly one APGAR sum score and contains all five sub scores as component observations.
  • Assume that a business rules says that iIf APGAR sum score < 4 (which is considered to be critical) then the whole panel its required to be included, otherwise sum score only is considered to be sufficient.

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).


Simple Observation Template: Gravida

This is an example of a template defined in DECOR* (Data Elements, Codes, OIDs and Rules). The example is about the number of gravidities of a woman including a possible actual one, e.g. a woman is gravida 2, i.e. she has been or is pregnant two times so far. The observation code is bound to 11996-6 from LOINC. The number of gravidities is (observation value) is demoted to be a count (INT) and restricted to be valued zero up to 75 (no reports seen so far about a number of pregnancies larger than 75). The template comes with a valid example.

<template id="2.999.999.997.10.1002" name="Gravidity" displayName="Gravidity" effectiveDate="2011-06-22T00:00:00" statusCode="active">
   <element name="hl7:observation">
           <observation classCode="OBS" moodCode="EVN">
               <value xsi:type="INT" value="2"/>
       <attribute classCode="OBS" moodCode="EVN"/>
       <element name="hl7:code" minimumMultiplicity="1" maximumMultiplicity="1" isMandatory="true" datatype="CE">
           <vocabulary code="11996-6" codeSystem="2.16.840.1.113883.6.1"/>
       <element name="hl7:value" minimumMultiplicity="1" maximumMultiplicity="1" id="2.999.999.997.77.5.701" datatype="INT">
           <property minInclude="0" maxInclude="75"/>

*DECOR allows a consistent collection of information from a clinical view (functional specification), codes (i.e. value set definitions), identifiers (OIDs), and rules (templates to constrain XML instances). As for the "rules" part the DECOR canonical format is transformed into a package of schematron rules (including references to all used value sets and data types) which is called the "runtime" environment. In addition, a documentation of the template definitions (among others in HTML format that can be made directly accessible thru schematron error, warning and information messages).

Simple Observation Template: Body Height

This is an example template in DECOR format defining a person's body height. A short description is given in three languages. The observation is a physical quantity (PQ) and has either a unit "m" (meters) with a valid range of 0..3 with two fraction digits required, or a unit "cm" (centimeters) with a value ranged 0..300 (tallest human ever documented was 272 cm so far). This template can act as a parent template that further restricts the use of the value to be e.g. "cm" only, ranged from 120..245 etc.

<template id="2.999.999.997.10.1000" name="BodyHeight" displayName="Body height" effectiveDate="2011-07-14T00:00:00" statusCode="active">
   <desc language="nl-NL">Lichaamslengte van een persoon</desc>
   <desc language="de-DE">Körperlänge einer Person</desc>
   <desc language="en-US">Body height of a person</desc>
   <element name="hl7:observation">
           <observation classCode="OBS" moodCode="EVN">
               <value xsi:type="PQ" value="173" unit="cm"/>
       <attribute classCode="OBS" moodCode="EVN"/>
       <element name="hl7:code" minimumMultiplicity="1" maximumMultiplicity="1" isMandatory="true" datatype="CE">
           <vocabulary code="3137-7" codeSystem="2.16.840.1.113883.6.1"/>
       <element name="hl7:value" minimumMultiplicity="1" maximumMultiplicity="1" id="2.999.999.997.77.5.760" datatype="PQ">
           <property unit="m" minInclude="0" maxInclude="3" fractionDigits="2!"/>
           <property unit="cm" minInclude="0" maxInclude="300" fractionDigits="0!"/>

Links to material so far (somewhat outdated)

return to Main page