Template metadata is mainly defined in the “Business Requirements for Template Registries” [ref follows]. In order to support template registries and to allow the appropriate use of templates, the following metadata is associated with each template.
- 1 Template Meta Data and Design Body
- 2 Meta data of templates (rule elements)
- 2.1 template/@id
- 2.2 template/@name
- 2.3 template/@effectiveDate
- 2.4 template/@statusCode
- 2.5 template/@displayName
- 2.6 template/@versionLabel
- 2.7 template/@expirationDate
- 2.8 template/@officialReleaseDate
- 2.9 template/@isClosed
- 2.10 template/desc
- 2.11 template/classification
- 2.12 template/relationship
- 2.13 template/context
- 2.14 template/item
- 2.15 template/example
- 3 Template design body definitions
- 3.1 element
- 3.1.1 element/@name
- 3.1.2 element/@minimumMultiplicity
- 3.1.3 element/@maximumMultiplicity
- 3.1.4 element/@isMandatory
- 3.1.5 element/@conformance
- 3.1.6 element/@datatype
- 3.1.7 element/@strength
- 3.1.8 element/@id
- 3.1.9 element/@contains
- 3.1.10 element/@flexibility
- 3.1.11 element/@isClosed
- 3.1.12 element/desc
- 3.1.13 element/item
- 3.1.14 element/example
- 3.1.15 element/vocabulary
- 3.1.16 element/property
- 3.1.17 element/text
- 3.2 attribute
- 3.3 choice
- 3.4 include
- 3.5 constraint
- 3.6 Schematron statements
- 3.1 element
- 4 Versioning aspects
- 5 Expressing Constraints in Templates
- 5.1 Data Type Constraints
- 5.2 Cardinality
- 5.3 Mandatory / Conformance
- 5.4 Allowed Data Absent Reasons (Null Flavors)
- 5.5 Fixed Values
- 5.6 Default Values
- 5.7 List of Allowed Values
- 5.8 Quantity Ranges
- 5.9 Units
- 5.10 Fractional Digits
- 5.11 Textual Restrictions
- 5.12 Vocabulary Conformance
- 5.13 Inclusion and Containment Relationships
- 5.14 Co-Occurance
- 5.15 Originator Responsibilities: General Case
- 5.16 Recipient Responsibilities: General Case
- 5.17 Examples
Template Meta Data and Design Body
Templates have meta information about their identity, effective date, status etc referred to as the Template Meta Data and the actual set of constraint definitions referred to as the Template Design Body. The following sections specify the template meta data (rule element) and design body elements that are used to define a whole template.
Meta data of templates (rule elements)
The following table gives an overview of the template meta data structure.
|@officialReleaseDate||TimeStamp||0..1||R||Official Release Date|
|desc||FreeText||0..*||R||Multilingual description of purpose and scope|
|@type||Enumeration||0..1||R||Type of Template|
|@format||Enumeration||0..1||R||Format of Template|
|tag||NonEmptyString||0..*||R||Tags for search purposes|
|@type||Enumeration||0..1||C||Type of Relationship|
|@template||BasicIdOrOid||0..1||C||Related Template name or id|
|@model||NonEmptyString||0..1||C||Related Template name or id|
|@flexibility||StaticOrDynamicFlexibility||0..1||C||Tags for search purposes|
|@id||SelfReferenceTemplateIdOrOid||0..1||C||Type of template id as context, either “*” or “**” or an OID|
|item||0..1||R||Template item label and description|
|@label||NonEmptyString||1..1||M||String to identify item (template) during validation|
|desc||FreeText||0..1||R||Further explanation of the item label|
|@type||Enumeration||0..1||R||Type of example, valid or error|
|@caption||NonEmptyString||0..1||R||Caption for the example|
|(element content)||(any well formed XML)||1..1||M||The example XML fragment|
A mandatory globally unique, non-semantic, identifier for the template as the primary identifier. It is the identification of the purpose or intent of the template and is typically an OID. The id or the name of a template is chosen when referencing the template in another design, such as inclusion or containment.
<template id="2.16.840.1.1138188.8.131.52.4.31" …
A required name as a business name for the template as a secondary identifier. Please note that there is no guarantee that the name is globally unique but it shall be unique within a governance group. Name or id of a template is chosen when referencing the template in another design, such as inclusion or containment.
<template … name="AgeObservation" …
The template has a mandatory timestamp (date and optional time) after which the template existed, regardless of its state (e.g. still in design phase or ready for use). The date can be seen as the point in time “when the template came into being” or when it became “in effect” for the governance group. Use of the template prior to this date would be considered an invalid use of the template.
The rationale behind a mandatory effective date as a version identification property is that it can be expected that a template designer always knows when “his” template first came into being, i.e. when he starts the work on template meta data or design body. It is important to distinguish between the effective date (in effect for the governance group) and an “official release date” (see later).
<template … effectiveDate="2013-11-13T00:00:00" …
The mandatory status of the template.
Every version of a template has a status. The status indicates the level of maturity of the design and may be used to manage the use of the design. While different template governance organizations may establish additional status states to support local template management practices, or chose to reduce the number of statuses it uses, the follow set of statuses have been defined. According to the Business Requirements for Template Registries ART-DECOR uses the following subset of status codes of a template (in bold).
|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 governance group (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 was published but 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. During the development proces of a template design (new, draft) it was decided that further development on this template will not happen.|
|cancelled||Template was never published and is withdrawn.|
|update||Template is undergoing an 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 governance group (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 (new version date but 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 (version), which is linked to the retired template.|
<template … statusCode="active" …
The optional human readable display name for the template for orientation purposes. This is not intended for machine processing and typically created in the project’s language or in English.
A version of a template may contain an optional human readable version label for the template to be able to determine the correct version of a template.
Some governance groups may make this label to be mandatory, IHE for example requires the use as a version label as “version identifier” which is used in conjunction with the template identifier to uniquely identify a version of a template.
<template … versionLabel="v2.0" …
The optional date at which the concept represented by this template becomes stale, and should be reviewed for (clinical) relevance and accuracy. The expirationDate is set to indicate that it should/shall no longer be used for new designs (by anyone), i.e. another template design that uses this template by inclusion or containment after this date would be considered venturesome.
A template may be released (published) by the governance group in any status it might have. However it may be useful to set an “official” date since when the template is ready for use (trial implementation, production etc.). This is done by populating the optional “official release date”.
An optional Boolean value that indicates whether the template is defined as closed or not. The default is “false” (i.e. template is defined as “open”). An “open” template should not have @isClosed or @isClosed set to “false”. A “closed” template shall have an @isClosed set to “true”.
<template … isClosed="true" …
See also Open vs closed Templates.
An optional and repeatable 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. Format: string with optional HTML tagging (XHTML). Supports @language, see @defaultLanguage.
An optional and repeatable element that allows the classification of the template.
The @type of the template, at this point in time something like one of the following
|cdadocumentlevel||CDA document level|
|cdaheaderlevel||CDA header level|
|cdasectionlevel||CDA secton level|
|cdaentrylevel||CDA entry level|
|clinicalstatementlevel||in a message, a clinical statement constraint|
|datatypelevel||a data type template, aka data type flavor|
The format of the instance the template constrains.
As of now the only format that is supported is "HL7 V3 XML ITS 1", i.e. "hl7v3xml1". This is the default.
In the future there might be other types of instances, e.g. “fhirxml” for FHIR-XML, “greencda” for green CDA instances or “genxml” for generic XML etc.
In addition, tag elements could be incorporated to specifiy any number of tags for search purposes.
<classification type="cdaentrylevel"> <tag>Blood pressure</tag> </classification>
This optional and repeatable element defines relationships of the template regarding other templates or model artifacts. The type of relationship is indicated in the @type attribute.
The relationship element shall have a value in either @template or @model, but not both. The attribute @flexibility reflects the binding type for @template or @model, depending on which is valued.
The @type of the relationship of the template, at this point in time one of the following.
|REPL||This template replaces @template|
|SPEC||This template specializes @template|
|GEN||This template generalizes @template|
|COPY||This template is a design copy of @template|
|ADAPT||This template is an adaptation of @template|
|EQUIV||This template is equivalent to @template regarding design|
|VERSION||This template is a version of @template (as ART-DECOR is a proper registry, this relationship is automatically derived)|
|BACKWD||This template is backward compatible of @template|
|FORWD||This template is forward compatible to @template|
|CONTAINS||This template contains (uses) @template (as ART-DECOR is a proper registry, this relationship is automatically derived)|
|INCLUDES||This template includes (uses) @template (as ART-DECOR is a proper registry, this relationship is automatically derived)|
|DRIV||This template is derived from model or other artifact expressed or specified in the @model attribute|
A reference by name or id to a template identifer, used for template-template relationships.
A reference to a model artifact identifier or description specifying from what this template is derived from or based on, e.g. an HL7 R-MIM, a DCM, used for template-model relationships.
Static or dynamic binding for the template or model that is referred. Default value is 'dynamic'.
<relationship type="SPEC" template="2.16.840.1937.10.101" flexibility="dynamic"/> <relationship type="ADAPT" template="1.3.1937.10.102" flexibility="2013-02-10T00:00:00"/> <relationship type="DRIV" model="some-model-name-or-id"/>
An optional context of the template, i.e. where in an XML instance the template rules are considered to apply 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 and for example be triggered by a templateId in an instance, 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. This means that the context for validation is: all sibling nodes of any templateId element in an instance where the @root is populated with the same id as the template @id.
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 trigger templates in an instance without the need to have template id elements in the instance.
The optional item is used as an identification mechanism when it comes to error or warning or information messages by derived validation scripts. For example if each constraint has a (unique) number, it may be used to precede every validation message.
Template item label as string. The default is the template name.
Further explanation of the item label.
Templates may have zero to many example fragments to illustrate valid (or explicitly invalid) instances. In addition, each template element definition (see below) may have also an example fragment.
The type of the example, either
|@type||Description and rendering|
|valid||will render the example in green|
|error||will render the example in red|
not set (default)
|will render the example "normally"|
An optional text used as caption for the example
Template design body definitions
The actual template design, also seen as the “body” of the template, is a collection of constraints that ideally describes the structure and semantics of all instance elements. It an contains the following items
- template element definitions with possible vocabulary, property or element content (text) constraints,
- template element attribute definitions with possible vocabulary constraints,
- choices of template elements,
- inclusions of other templates and
- to support at least one typical constraint language schematron rules (assert, report, let) are allowed.
The name of the element, typically prefixed by the default project namespace (e.g. “hl7:” or “cda:”). Declaration of prefixes for elements in other namespaces is done on the Decor_root_element.
May be an XPath expression and predicated.
This optional attribute identifies the minimum number of repetitions of this element that may occur. This is a small non-negative integer. (If not present, the element may occur zero times as far as this element definition is concerned, unless it is mandatory, in which case it must occur at least once.)
This optional attribute identifies the maximum number of repetitions of this element that may occur. This is either a small non-negative integer or “*” to indicate “unbound” repetitions. (If not present, the element may occur multiple times as far as this element definition is concerned.)
<element … maximumMultiplicity="2" … > <element … maximumMultiplicity="*" … >
This optional boolean attribute identifies that this element is mandatory, i.e. in an instance it shall be populated with a valid value. A mandatory element cannot have conformance 'NP' or 'C', and cannot have a minimumMultiplicity of 0.
This optional attribute identifies the conformance of this element. Allowed values are shown in the following table.
This optional attribute specifies the data type or a data type flavor for this element.
A complete list of the supported data types can be found here.
This optional attribute specifies the vocabulary strength for data types that support that feature. Examples include CD, CE, CV and CO. Values are required, extensible, preferred and example. Default is required. Mismatches with required lead to validation errors (SHALL logic). Mismatches with extensible lead to validation warnings (SHOULD logic). Mismatches with preferred lead to validation information messages (MAY logic). Mismatches with example don't have any validation consequences.
The formerly supported values CNE (Coded No Extensibility) and CWE (Coded With Extensibility) are deprecated as of December 2017. Specification CNE is handled as required and CWE is handled as extensible.
|required||Required/CNE. Coded with no exceptions; this element SHALL be from the specified value set|
|extensible||Extensible/CWE. Coded with Exceptions; this element SHALL be from the specified value set if any of the codes within the value set can apply to the concept being communicated. If the value set does not cover the concept (based on human review), alternate codings (or, data type allowing, text) may be included instead.|
|preferred||Preferred. Instances are encouraged to draw from the specified codes for interoperability purposes but are not required to do so to be considered conformant.|
|example||Example. Instances are not expected or even encouraged to draw from the specified value set. The value set merely provides examples of the types of concepts intended to be included.|
This optional attribute is an id that allows the element to be uniquely identified. The same id cannot occur on any other element or attribute within this version of the template (template id and effectiveDate). This is typically done using an OID. The id can be used link between a template element and an associated concept for example in a data set or functional model.
A @contains attribute indicates that the element contains the template specified by @contains. This may be a valid template name or template id.
Please note that a contained template typically influences the predicate of the element. See sections about re-use of templates (includes and contains) for further information.
<element name="cda:entry" contains="AgeObservation" …
An optional static or dynamic binding for the rule set that is referred to by @contains. Default value is “dynamic”, i.e. use the most recent version of the specified contained template.
<element name="cda:entry" contains="184.108.40.206.5" flexibility="2013-11-23"…
This optional boolean attribute allows to specifiy that the element and subsequent child nodes are considered as open (other elements than specified allowed) or closed (no other elements than specified allowed). The rationale is the same as for open or closed templates, except that this definition applies to element and its child elements only.
See also Open vs closed Templates.
This optional sub-element carries the multilingual textual description or further explanation on the use of the element.
Indicates the item label of the element for errors, warnings etc., see also Template item
An template element may have zero or more examples or example fragments for the element, see also Template example
This optional sub-element is used for elements with "coded" data types. It allows the assertion of one or more codes, code systems, value sets or concept domains.
- A @valueSet (by name or id) plus an optional @flexibility attribute which is either the fixed string "dynamic" or a valid date and time as an effective date of the version of the value set (static).
- A @code and (depending on the data type) a @codeSystem; it may contain human readable attributes such a @displayName and @codeSystemName which, if present, constraints the presence of these attributes in instances.
- An @domain specification by name, defining the abstract concept domain(s) from which proper codes may be drawn.
<element name="hl7:code" … datatype="CV"> <vocabulary valueSet="MyValueSet" flexibility="dynamic"/> </element> <element name="hl7:code" … datatype="CE"> <vocabulary valueSet="MyValueSet" flexibility="2013-11-24"/> </element>
<element name="hl7:code" … datatype="CE"> <vocabulary code="1234" codeSystem="220.127.116.11.5"/> </element>
If multiple vocabulary elements are specified the definitions are logically connected by an "OR".
<element name="hl7:code" … datatype="CE"> <vocabulary valueSet="AAA" flexibility="dynamic"/> <vocabulary valueSet="BBB" flexibility="dynamic"/> <vocabulary code="1234" codeSystem="18.104.22.168.5"/> </element>
This attribute specifies the value set by name or id where codes shall be drawn from.
This attribute specifies the flexibility for the value set.
This attribute specifies the code that shall be used in the instance.
This attribute specifies the code system (e.g. an OID) that shall be used in the instance.
This attribute specifies the human readable display name that shall be used in the instance.
This attribute specifies the human readable code system name that shall be used in the instance.
This attribute specifies the conceptual domain by name where codes shall be drawn from.
<element name="hl7:code" … datatype="CE"> <vocabulary domain="TheConceptDomain"/> </element>
Please note that specifiying a domain typically leads to no testable properties in an instance. A conceptual domain is used for coded elements in templates that typically are further constrained.
The property sub-element is used for elements of type quantity, string or boolean. It allows the assertion of one or more units, ranges, fraction digits or fixed values.
|@unit||A proper (UCUM) unit.|| cm
|@currency||A currency unit.||EUR|
|@minInclude||An integer or decimal number to specify the lower inclusive interval boundary||1.00|
|@maxInclude||An integer or decimal number to specify the upper inclusive interval boundary||38|
|@fractionDigits||A small positive integer that specifies the number of fractional digits.
A fraction digit "2" requires at least two fraction digits to be present in the instance, otherwise the instance is in error. If fraction digit is suffixed with a "!", e.g. "2!" this means the presence of two fraction digits.
|@minLength||A positive integer number to specify the minimal length of a string||1|
|@maxLength||A positive integer number to specify the maximal length of a string||10|
|@value||A string as a fixed value.||XYZ|
Valid combinations of attributes are:
- @unit @minInclude @maxInclude @fractionDigits (for physical quantities in @value)
- @currency @minInclude @maxInclude @fractionDigits (for monetary amounts in @value)
- @minLength @maxLength (for strings)
- @value (fixed values in @value)
<element name="hl7:value" … datatype="PQ"> <property minInclude="1" maxInclude="200" unit="cm" /> </element>
If multiple property elements are specified the definitions are logically connected by an "OR".
<element name="hl7:value" … datatype="PQ"> <property minInclude="1" maxInclude="200" unit="cm"/> <property minInclude="0.01" maxInclude="2.00" unit="m" fractionDigits="2!"/> </element>
This optional sub-element specifies the element content in an instance. This is used for elements of type ST, ED etc.
<element name="hl7:text" … datatype="ST"> <text>Fixed text to be used in the instance<text/> </element>
If multiple text elements are specified the definitions are logically connected by an "OR".
This definition allows to specify attributes for template elements and their properties.
Specifies the name of the XML attribute. It is typically used in conjunction with a @value.
<element name="hl7:observation" … > <attribute name="classCode" value="OBS"/> </element>
<attribute name="negationInd" value="true"/>
Specifies the value of the XML attribute given in @name.
HL7 short cuts
For HL7 V3 instances there are a couple of attribute @name/@value short cuts in ART-DECOR defined. These attributes can be used instead of the standard @name/@value pair. Some of the attributes may also contain lists of values, all items separated by an "|". This is the list of HL7 V3 shortcuts including the attribute datatype:
|HL7 v3 Attribute||Datatype|
<attribute determinerCode="INSTANCE"/> <attribute classCode="OBS" moodCode="EVN"/> <attribute typeCode="PRCP|TRC"/>
|Note that any of this HL7 V3 short cuts can also be expressed as "normal" @name/@value pairs. The ART template editor always replaces HL7 short cuts by the name-value pairs.|
This option attribute determines that the attribute is requird to be valued in the instance. Default is 'false', meaning that the attribute is NOT optional, and thus required.
<attribute name="classCode" value="OBS" isOptional="true"/>
Determines that the attribute is prohibited to be in the instance.
<attribute name="nullFlavor" prohibited="true"/>
This optional attribute allows to specify the datatype of the XML attribute. Valid types are shown in the table below.
|st||string, the default||"a string"|
|set_cs||set of (space-delimited) codes||"B64 A12"|
<attribute name="mediaType" datatype="cs"/>
This optional sub-element carries the multilingual textual description or further explanation on the use of the element.
Indicates the item label of the attribute for errors, warnings etc., see also Template item
This optional sub-element is used for attributes with "coded" data types, i.e. "cs" or "set_cs". It allows the assertion of one or more value sets.
In validation it is assumed that multiple codes may be used as is possible in e.g. @use on datatypes AD, EN and TEL. In order to constrain to only one possible code, the @datatype attribute must be set to "cs" (only one single code allowed). Alternatively, and also the default, use "set_cs" (one or multiple space delimited codes allowed).
The value set where the code shall be drawn from, referenced by name or id of the value set.
<attribute name="mediaType" datatype="cs"> <vocabulary valueSet="MyMediaTypes" flexibility="dynamic"/> </attribute>
<attribute name="use" datatype="set_cs" isOptional="true"> <vocabulary valueSet="AddressUse" flexibility="dynamic"/> </attribute>
Another example is how to determine the set of allowed nullFlavors for any element. Assume the following definition of a doseQuantity element, then the included attribute definition constraints the set of allowed nullFlavors (defined in an value set shown below as well).
<element name="hl7:doseQuantity" minimumMultiplicity="1" maximumMultiplicity="1" conformance="R" datatype="IVL_PQ"> <attribute name="nullFlavor" datatype="cs" isOptional="true"> <vocabulary valueSet="AllowableNulls"/> </attribute> </element>
And the corresponding value set might look like:
<valueSet id="2.16…." name="AllowableNulls" displayName="AllowableNulls" effectiveDate="2013-03-25T14:13:00" statusCode="final"> <conceptList> <concept code="NI" codeSystem="2.16.840.1.113883.5.1008" displayName="no information" level="0" type="L"/> <concept code="UNK" codeSystem="2.16.840.1.113883.5.1008" displayName="unknown" level="0" type="L"/> <concept code="OTH" codeSystem="2.16.840.1.113883.5.1008" displayName="other" level="0" type="L"/> </conceptList> </valueSet>
This optional attribute is an id that allows the attribute to be uniquely identified. The same id cannot occur on any other element or attribute within this version of the template (template id and effectiveDate). This is typically done using an OID. The id can be used link between a template attribute and an associated concept for example in a data set or functional model.
In some cases a designer wants to offer a choice of template elements and restrict the choice to be n out of m (cardinality constraint). In order to be able to specify choices of elements the choice element can be used.
Optional, identifies the minimum number of elements out of the choice.
Optional, identifies the maximum number of elements out of the choice.
A template may reference another defined template by inclusion.
An inclusion within a template design makes use of another template by “virtually” copying the included template definitions, also known as transclusion. In essence this means that template definitions are included by reference and shown as-is on demand, i.e. at time of displaying the template or using it for the creation of validation scripts.
Inclusion is automatic and transparent to the user.
Mandatory reference to the template to be included, either by name or id.
<element name="hl7:ClinicalDocument"> <include ref="CDAtypeId"/> <element name="hl7:templateId" minimumMultiplicity="1" maximumMultiplicity="1" isMandatory="true" datatype="II"> <desc language="en-US">CDA document template id for this kind of document</desc> <example> <templateId root="2.16.840.1.113883.3.1922.214.171.124.10.1"/> </example> <attribute root="2.16.840.1.113883.3.19126.96.36.199.10.1"/> </element> <include ref="CDAid"/> <element name="hl7:code" minimumMultiplicity="1" maximumMultiplicity="1" isMandatory="true" datatype="CE"> <example> <!-- document type --> <code code="11524-6" codeSystem="2.16.840.1.113883.6.1" codeSystemName="LOINC" displayName="EKG study report"/> </example> <vocabulary code="11524-6" codeSystem="2.16.840.1.113883.6.1"/> </element> <include ref="CDAtitle" minimumMultiplicity="0" maximumMultiplicity="1"> <example> <title>EKG Report as of 1 February 2013</title> </example> </include> <include ref="CDAeffectiveTime"/> <include ref="CDAconfidentialityCode"/> <include ref="CDArecordTarget" minimumMultiplicity="1" maximumMultiplicity="1"/> <include ref="CDAauthor" minimumMultiplicity="1" maximumMultiplicity="1"/> <include ref="CDAcustodian"/> ... </element>
The optional attribute identifies the minimum number of repetitions of all elements at top level of the included template.
The include statement may specify overriding cardinalities/conformances. If the included template has only one root element the cardinality/conformance of this element gets overridden by the cardinality/conformance specified in the calling include statement. If there are more than one root element in the included template, all elements are overridden.
Optional, identifies the maximum number of repetitions of all elements at top level of the included template.
Optional, identifies whether all elements at top level of the included template are mandatory
Optional, identifies the conformance of all elements at top level of the included template.
A multilingual textual description for the include.
Indicates the item label for the include for errors, warnings etc., see also Template item
Zero or more examples for the item label, see also Template example
An optional and repeatable free text, natural language and non computable description of constraints applicable in this context. May contain markup and supports the @language attribute. Occurs max once only per language. Format: string with optional HTML tagging (XHTML). Supports @language, see @defaultLanguage.
You MAY also convey the same constraints in the <desc> element but separating them out into constraints allows different rendering in your publications making the constraints stand out more than they would in <desc>.
<constraint language="en-US">If the attribute qualifier is used for this element it should be derived from epSOSEntityNamePartQualifier 2.16.840.1.113883.5.43</constraint>
<constraint language="en-US">The <functionCode> element is mandatory when this participant is the preferred HP</constraint> <constraint language="nl-NL">Het element <functionCode> is mandatory wanneer deze participant de geprefereerde zorgaanbieder/zorgverlener is</constraint>
To support at least one typical constraint language schematron rules (assert, report, let) are allowed in template definitions. They may be interspersed at defined locations.
This statement will be converted to an appropriate schematron assert statement. They are often used to express co-constraints.
<assert role="error" test="../hl7:observation/@negationInd or hl7:value"> If the observation is not null a value shall be present </assert>
Schematron flag to convey state or severity information to a subsequent process
URI value of the external information of interest
One of the following: “error”, “warning” or “information”
Schematron test expression
This statement will be converted to an appropriate schematron report statement. They are often used to express co-constraints.
Schematron flag to convey state or severity information to a subsequent process
URI value of the external information of interest
One of the following: “error”, “warning” or “information”
Schematron test expression
A let statement defines a schematron runtime variable that can be used in assert or report or let statements.
<let name="lepcode" value="//hl7:observation[hl7:code[@code='123-4']]/hl7:value/@code"/>
Schematron let name of the variable
Schematron let value
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.
Optionally a @versionLabel may be assigned as an alternative representation for the @effectiveDate, e.g. "v1.1" or "1.3.4b". This is for human readability convenience only.
Any change to the semantic meaning or intention 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 template item. 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 template item 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).
A complete list of supported data types and flavors can be found here.
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.
The cardinality indicator (0..1, 1..1, 1..*, etc.) specifies the allowable occurrences within a document 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
This guide uses cardinalities for element and attribute definitions where attribute definitions can be either 0..0 (prohibited, not allowed), 0..1 (optional), and 1..1 (required).
Mandatory / Conformance
Elements that are defined to be mandatory must be populated with valid data. If an element is not flagged as mandatory, data may be absent, e.g. by using a nullFlavor or the element may be simply omitted if optional.
The conformance expresses whether a system must support an element or not.
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||Shown as||Minimum Cardinality||nullFlavor ok?||Comment|
|yes||R||M||1||No||Shall be present and valued in a message|
|no||R||R||0||Yes||If no information is available, just don't send it|
The item 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 template item table, a shorthand for “mandatory” with required conformance.
The item 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 template item table.
The item is truly optional, i.e. a valid value may be provided or if missing may be omitted.
It is indicated as “O” in the template item table, a shorthand for an unspecified conformance with a minimum cardinality of zero.
Not present (NP)
The item is not allowed, i.e. the number of allowable occurrences is 0. It is indicated as “NP” in the template item table.
This item has an associated condition predicate and may depend on the co-occurance of other elements or properties of the instance or situations. 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 template item table, followed immediately by the condition predicate table.
This is used for attributes only and indicates that an attribute has a fixed value. It fixed value shall appear in an XML instance.
It is indicated as “F” in the template item 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 template 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 template item table. There is no cardinality specified.
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.
The most frequent use of fixed values is a structural attribute. 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).
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.
For quantities like real and integer it may be useful to specify allowed ranges in a template. This is typically done by defining a lower (minInclude) and a higher (maxInclude) boundary.
For physical quantities (HL7 data type PQ) it is useful to specify allowed units. For HL7 PQ items this has to be a UCUM expression.
Please note that quantity ranges are related tot heir units and therefore need to be grouped appropriately if there is more than one allow unit.
In some cases it makes sense to constrain the number of fraction digits for physical quantities / real number. This may include a required number of fraction digits or an indication of the maximum number of fraction digits.
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.
For coded elements a template design may restrict the use of terms from a specific code system. 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., value set with OID 2.16.840.1.1138188.8.131.52 / name HL7ObservationInterpretation do not appear in messages/documents. They tie the conformance requirements of an implementation guide to the appropriate code system for validation (vocabulary binding).
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.
Inclusion and Containment Relationships
One of the design principles of templates is the re-usability: a template, once defined, may be used again in any context wherever appropriate. From practice, two kinds of “re-use” mechanism are known.
An inclusion within a template design makes use of another template by “virtually” copying the included template definitions, also known as transclusion. In essence this means that template definitions are included by reference and shown as-is on demand, i.e. at time of displaying the template or using it for the creation of validation scripts. Inclusion is automatic and transparent to the user.
Example: a CDA document level template includes the definitions of a CDA typeId, effectiveTime, title and setId+versionNumber.
A containment within a template design is a reference to another template without actually showing the contained definitions. A typical situation is a CDA section that may contain entries. The reference only is part of the section definition. The definition of the entry itself remains part of the entry level template.
Example: a CDA section Pregnancy Information Section contains a Estimated Delivery Date Observation Entry.
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 this 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).
- This page was last modified on 19 December 2017, at 13:01.
- This page has been accessed 1,595,315 times.