Difference between revisions of "DECOR-rules"

m (Co-Occurance: typo)
(element/@strength)
Line 407: Line 407:
  
 
====element/@strength====
 
====element/@strength====
This optional attribute specifies the vocabulary strength for data types that support that feature. Examples include CD, CE, CV and CO. Values are CNE (Coded No Extensibility) and CWE (Coded With Extensibility). Default is CNE. Mismatches with CNE lead to validation errors (SHALL logic). Mismatches with CWE lead to validation warnings (SHOULD logic)
+
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.
 +
 
 +
{| class="artdecor" id="bindingStrength"
 +
! @strength !! Description
 +
|-
 +
| 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.
 +
|}
  
 
====element/@id====
 
====element/@id====

Revision as of 21:53, 14 December 2017

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.

Contents

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.

Item DT Card Conf Description
template Root element
   @id Oid 1..1 M Identification
   @name ShortFormalName 1..1 M Business name
   @effectiveDate TimeStamp 1..1 M Start Date
   @statusCode Enumeration 1..1 M Status
   @displayName NonEmptyString 0..1 R Print Name
   @versionLabel NonEmptyString 0..1 R Version Label
   @expirationDate TimeStamp 0..1 R Expiration Date
   @officialReleaseDate TimeStamp 0..1 R Official Release Date
   @isClosed Boolean 0..1 R Open/Closed Template
   desc FreeText 0..* R Multilingual description of purpose and scope
   classification 0..* R Classification
     @type Enumeration 0..1 R Type of Template
     @format Enumeration 0..1 R Format of Template
     tag NonEmptyString 0..* R Tags for search purposes
   relationship 0..* R Relationships
     @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
   context 0..1 R
     @id SelfReferenceTemplateIdOrOid 0..1 C Type of template id as context, either “*” or “**” or an OID
     @path AnyURI 0..1 C
   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
   example 0..* R XML example
     @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

template/@id

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.113883.10.20.22.4.31" 

template/@name

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" 

template/@effectiveDate

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" 

template/@statusCode

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

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 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.
Information.svg A template registry may consider all status codes (also those in italics) that are defined in the Business Requirements for Template Registries. The template itself is considered to need only the codes mentioned above and the experience of several years using ART-DECOR showed that this is sufficient.
<template  statusCode="active" 

template/@displayName

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.

template/@versionLabel

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" 

template/@expirationDate

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.

template/@officialReleaseDate

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

template/@isClosed

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.

template/desc

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.

template/classification

An optional and repeatable element that allows the classification of the template.

template/classification/@type

The @type of the template, at this point in time something like one of the following

@type Description
cdadocumentlevel CDA document level
cdaheaderlevel CDA header level
cdasectionlevel CDA secton level
cdaentrylevel CDA entry level
messagelevel message level
clinicalstatementlevel in a message, a clinical statement constraint
datatypelevel a data type template, aka data type flavor
<classification type="cdaheaderlevel"/>

template/classification/@format

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.

template/classification/tag

In addition, tag elements could be incorporated to specifiy any number of tags for search purposes.

<classification type="cdaentrylevel">
  <tag>Blood pressure</tag>
</classification>

template/relationship

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.

template/relationship/@type

The @type of the relationship of the template, at this point in time one of the following.

Type Description
Template-template relationships
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)
Template-model relationships
DRIV This template is derived from model or other artifact expressed or specified in the @model attribute
Alert2.svg TODO: add examples of allowable actions on the template, based on the type of relationship. E.g. when you specialize, you may constrain datatype, cardinality, conformance, value sets etc. When you generalize a template, you may add elements, use value sets that are super sets etc.

template/relationship/@template

A reference by name or id to a template identifer, used for template-template relationships.

template/relationship/@model

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.

template/relationship/@flexibility

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

template/context

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.

<context id="*"/>

parent node context

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

<context id="**"/>

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.

Example

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.

<context path="hl7:recordTarget"/>

template/item

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.

Example

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

<item label="CONF:7941"/>

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

template/item/@label

Template item label as string. The default is the template name.

template/item/desc

Further explanation of the item label.

template/example

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.

template/example/@type

The type of the example, either

@type Description and rendering
valid will render the example in green
error will render the example in red
neutral
not set (default)
will render the example "normally"

template/example/@caption

An optional text used as caption for the example

Example

The following statement

<example type="valid" caption="A valid example with a piece of text">
  <root>
    <element value="abc"/>
    <text mediaType="text/plain">I am the text example</text>
  </root>
</example>

would render as

Error creating thumbnail: Unable to save thumbnail to destination

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.

element

element/@name

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.

Example

hl7:recordTarget

May be an XPath expression and predicated.

element/@minimumMultiplicity

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

element/@maximumMultiplicity

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="*"  >

element/@isMandatory

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.

element/@conformance

This optional attribute identifies the conformance of this element. Allowed values are shown in the following table.

@conformance Description
R required
NP not present
C conditional

element/@datatype

This optional attribute specifies the data type or a data type flavor for this element.

Examples
  • CD
  • CE
  • ST
  • TS
  • IVL_TS
  • II.BSN.NL
  • TS.DATE.MIN

A complete list of the supported data types can be found here.

element/@strength

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.

@strength Description
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.

element/@id

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.

Example

A CDA recordTarget has an element "cda:birthTime" that is associated with the birth time of the patient. If the birthTime template element gets an id, it can be linked to a concept representation for example in a data set that shows the functional perspective.

element/@contains

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" 

element/@flexibility

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="1.2.3.4.5" flexibility="2013-11-23"

element/@isClosed

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.

element/desc

This optional sub-element carries the multilingual textual description or further explanation on the use of the element.

element/item

Indicates the item label of the element for errors, warnings etc., see also Template item

element/example

An template element may have zero or more examples or example fragments for the element, see also Template example

element/vocabulary

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.

Valid combinations

  • 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="1.2.3.4.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="1.2.3.4.5"/>
</element>
element/vocabulary/@valueSet

This attribute specifies the value set by name or id where codes shall be drawn from.

element/vocabulary/@flexibility

This attribute specifies the flexibility for the value set.

element/vocabulary/@code

This attribute specifies the code that shall be used in the instance.

element/vocabulary/@codeSystem

This attribute specifies the code system (e.g. an OID) that shall be used in the instance.

element/vocabulary/@displayName

This attribute specifies the human readable display name that shall be used in the instance.

element/vocabulary/@codeSystemName

This attribute specifies the human readable code system name that shall be used in the instance.

element/vocabulary/@domain

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.

element/property

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.

Property Attribute Description Example
@unit A proper (UCUM) unit. cm

mm[Hg]

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

2

2!

@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>

element/text

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

attribute

This definition allows to specify attributes for template elements and their properties.

attribute/@name

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

attribute/@value

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
@classCode cs
@moodCode cs
@determinerCode cs
@typeCode cs
@extension st
@operator cs
@contextControlCode cs
@institutionSpecified bl
@independentInd bl
@contextConductionInd bl
@inversionInd bl
@negationInd bl
@unit st
@code cs
@mediaType st
@representation st
@use cs
@qualifier cs
@nullFlavor cs
<attribute determinerCode="INSTANCE"/>

<attribute classCode="OBS" moodCode="EVN"/>

<attribute typeCode="PRCP|TRC"/>
Information.svg 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.

attribute/@isOptional

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

attribute/@prohibited

Determines that the attribute is prohibited to be in the instance.

<attribute name="nullFlavor" prohibited="true"/>

attribute/@datatype

This optional attribute allows to specify the datatype of the XML attribute. Valid types are shown in the table below.

Attribute datatype Meaning Example
st string, the default "a string"
bl boolean "true"
ts timestamp "20130630"
int integer "1"
real real "0.4"
cs code "B64"
set_cs set of (space-delimited) codes "B64 A12"
<attribute name="mediaType" datatype="cs"/>

attribute/desc

This optional sub-element carries the multilingual textual description or further explanation on the use of the element.

attribute/item

Indicates the item label of the attribute for errors, warnings etc., see also Template item

attribute/vocabulary

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

attribute/vocabulary/@valueSet

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>

attribute/@id

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.

choice

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.

Example

A typical example is the CDA header author definition where in the underlying model a choice is defined between an assignedPerson and an assignedAuthoringDevice playing the role of the author and where 0..1 playing entities may be chosen.

This can be expressed by specifying the following constraint

<choice minimumMultiplicity="0" maximumMultiplicity="1">
  <element name="assignedPerson">
    ...
  </element>
  <element name="assignedAuthoringDevice"
    ...
  </element>
</choice>

This offers the choice to select 0 or 1 out of the element assignedPerson or assignedAuthoringDevice. Their definitions are are not shown in this case.

choice/@minimumMultiplicity

Optional, identifies the minimum number of elements out of the choice.

choice/@maximumMultiplicity

Optional, identifies the maximum number of elements out of the choice.

include

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.

Examples

A CDA document level template includes the definitions of a CDA typeId, effectiveTime, title and setId+versionNumber. These items are defined as "includable" templates because they are used in other document level templates as well.

include/@ref

Mandatory reference to the template to be included, either by name or id.

<include ref="MyEffectiveTime"/>
<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.1937.99.60.3.10.1"/>
        </example>
        <attribute root="2.16.840.1.113883.3.1937.99.60.3.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>

include/@minimumMultiplicity

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.

Examples

In the following situation a templateX is included. Please note that regardless of the cardinality/conformance definitions of the root element hl7:code in templateX, it gets overridden by 0..1 as specified in the include statement. Also note that this is an override and not a formally checked restriction.

<template name="someTemplate"  >
  <element name="hl7:id"  />
  <include ref="templateX" minimumMultiplicity="0" maximumMultiplicity="1"></template>

<template name="templateX"  >
  <element name="hl7:code" minimumMultiplicity="1" maximumMultiplicity="*"  />
</template>

include/@maximumMultiplicity

Optional, identifies the maximum number of repetitions of all elements at top level of the included template.

include/@isMandatory

Optional, identifies whether all elements at top level of the included template are mandatory

include/@conformance

Optional, identifies the conformance of all elements at top level of the included template.

include/desc

A multilingual textual description for the include.

include/item

Indicates the item label for the include for errors, warnings etc., see also Template item

include/examples

Zero or more examples for the item label, see also Template example

constraint

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 &lt;functionCode&gt; element is mandatory 
when this participant is the preferred HP</constraint>
<constraint language="nl-NL">Het element &lt;functionCode&gt; is mandatory 
wanneer deze participant de geprefereerde zorgaanbieder/zorgverlener is</constraint>

Schematron statements

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.

assert

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>
assert/@flag

Schematron flag to convey state or severity information to a subsequent process

assert/@see

URI value of the external information of interest

assert/@role

One of the following: “error”, “warning” or “information”

assert/@test

Schematron test expression

report

This statement will be converted to an appropriate schematron report statement. They are often used to express co-constraints.

report/@flag

Schematron flag to convey state or severity information to a subsequent process

report/@see

URI value of the external information of interest

report/@role

One of the following: “error”, “warning” or “information”

report/@test

Schematron test expression

let

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"/>
let/@name

Schematron let name of the variable

let/@value

Schematron let value

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.

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.

Examples

Examples of template items 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
Item 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 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).

Examples
Item Description Data type (flavor)
id Instance identifier II
code A coded element CE
effectiveTime A time stamp TS
value A measurement of a physical quantity PQ
repeatNumber a non-negative integer INT.NONNEG
date A timestamp that may be valued up to a day TS.DATE

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.

Example repeatNumber

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

In a template you then can

  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.

Cardinality

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

Mandatory (M)

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.

Example

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

Required (R)

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.

Optional (O)

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.

Conditional (C)

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:

Card Conf Predicate
a1..b1 conf1 If condition1
a2..b2 conf2 If condition2
... ... ...
an..bn 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.

Example

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 is greater than 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 template item table, followed immediately by the condition predicate table.

Fixed (F)

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.

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

Example

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.

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

Example of fixed values for Structural Attributes
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

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.

Units

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.

Example

Body length

  • Unit = “cm”, ranges from 0 to 250
  • Unit = “m”, ranges from 0 to 2.50

Fractional Digits

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.

Textual Restrictions

regularExpression

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.

codingScheme

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.

Vocabulary Conformance

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.113883.1.11.78 / 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.
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

Verbatim

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

etc.

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.

<code code="11450-4" codeSystem="2.16.840.1.113883.6.1"/>

or

<code code="11450-4" codeSystem="2.16.840.1.113883.6.1"
      displayName="Problem List"  
      codeSystemName="LOINC"/>
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

Verbatim:

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

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.

Example

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.

Item DT Card Conf Description/Fixed value
component 1..1 R Contains GravidityObservation template id 2.16.840.1.113883.2.4.6.10.90.1053
  @typeCode CS 1..1 F COMP
Table: Template Item Table

Verbatim:

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

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.2.4.6.10.90.1053"/>
        <code code="11996-6" codeSystem="2.16.840.1.113883.6.1"/>
        <value xsi:type="INT" value="2"/>
    </observation>
 </component>

Co-Occurance

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.

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.2.4.6.10.90.1054
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.2.4.6.10.90.1055
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.

Table:

Attribute DT Card Conf Description/Fixed value
substanceAdministration
  @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.2.4.6.10.90.1054
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).

Examples

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">
        <example>
            <observation classCode="OBS" moodCode="EVN">
                <!-- Gravidity -->
                <code code="11996-6" codeSystem="2.16.840.1.113883.6.1"/>
                <value xsi:type="INT" value="2"/>
            </observation>
        </example>
        <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>
        <element name="hl7:value" minimumMultiplicity="1" maximumMultiplicity="1" 
            id="2.999.999.997.77.5.701" datatype="INT">
            <property minInclude="0" maxInclude="75"/>
        </element>
    </element>
 </template>

*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">
        <example>
            <observation classCode="OBS" moodCode="EVN">
                <code code="3137-7" codeSystem="2.16.840.1.113883.6.1"/>
                <value xsi:type="PQ" value="173" unit="cm"/>
            </observation>
        </example>
        <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>
        <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!"/>
        </element>
    </element>
 </template>