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

Talk:Template Functional Requirements

From HL7Wiki
Jump to navigation Jump to search

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

This document does not discuss implimentation of these requirements, which will be addressed in a different document.


Disclaimer


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

Acknowledgements


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


HL7 Template Metadata

Identification Metadata - Mandatory


LM: => Does this mean all of these elements are mandatory (can’t have a template unless they’re all filled in) or merely ‘required’ (all template registries must be able to capture this data and there must be a place for it in the MIF)?  If the latter, are any of these elements mandatory?
DK: => I believe these should be mandatory – an instance must have these values (no nulls!)


templateID

A globally unique, non-semantic, identifier for the Template. This is the primary identifier for all Templates.

 LM: Why must it be an OID?  A template is just a static model like any other and should 
be named accordingly.  OIDs may be used in the ‘realm’ portion of the identifier to 
indicate the organization or group responsible for the template.  
E.g. “RX=2.25.2034.15.82=123456=01” would be version 1 of the pharmacy template 123456 
issued by organization with the OID 2.25.2034.15.82. I’ve added support for OIDs as an 
optional “secondary” identifier.  However, primary identifier will still be the HL7 form. 
Note that the OID id is isn’t mandatory, though we could add a Schematron rule that makes 
it mandatory for LIMs (templates) if you want.


WG: Sources of this OID can be multiple organisations. Especially those 
organisations that are responsible for the clinical content could / should
 issue OIDs.
DK: It need not be an OID, but it needs to be a globally unique reference 
that can be used by look-up services and registries in an international 
distributed computing environment, and can be stored within each instance as a 
permanent record of the knowledge artefact to which it conforms. I would suggest 
that we postpone a final decision on the data type until we know how registry 
services might be established.templateName

templateName

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

 LM :=>Corresponds to “business name”.  There can be different business names for the same template 
in different realms and the names can exist in multiple languages.  Note that this isn’t mandatory,
 though we could add a Schematron rule makes it mandatory for the static model level for LIMs 
(templates) if you want.
 WG:=>Name will be available in different languages, representing the language in which the template
 is used.
 DK:=> This name is the primary “business name” in the natural language of the author. If coded, 
it can be cross-mapped to other coding schemes and languages on retrieval. A separate mechanism 
is proposed for representing descriptions in multiple languages. I do not agree that templates will
 be too numerous to name: it is not a requirement that the name be globally unique.

originatingAuthorEntityID

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

NOTE: Determining the form of the ID and its issuer etc is necessary but out of scope for the Templates SIG.

 LM:=> Who issues these?  Are they OIDs or what?  I believe this corresponds to 
header.responsibleGroup.groupId.  Note that this isn’t mandatory, though we could add 
a Schematron rule makes it mandatory for the static model level for LIMs (templates) if 
you want.
 DK:=> There is a need for us to define demographic registration policies to enable individuals
 to be authorized to be template authors, by a approved “scoping” organization. This is part 
of an editorial/certification policy that we will need to develop in the near future 
(openEHR is starting this now).

templateIntention

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

Example: The intention may include the realm or sub-realm within which the Template was designed to be used for.

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

 LM:=> Use the “UsageNotes” annotation which talks about how the static model is intended to be 
used and any constraints/restrictions on usage.  Note that this isn’t mandatory, though we could 
make it mandatory for the static model level for LIMs (templates) if you want.
 WG:=> Important issue. Also the purpose of Templates itself needs briefly addressed in a 
template description document: where can I use  templates for? And then: where can I use 
this particular template for in clinical documentation, messaging, data aggregation, DSS, 
queries etc. 
DK:=> Agreed – no change in the requirement statement is indicated.

templateVersion

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

NOTE: Changes to the Template that do not change the semantis or intention of the Template will constitute a new version of the Template being created. Any change to the semantic meaning of the Template will constitute the creation of a new Template.

LM:=> This is part of the identifier for the model.  This isn’t technically ‘required’ but will 
always be present before publication.  (I.e. when you’re in draft, you don’t have a version id.)
WG:=>Crucial for referring to it, but also in developmental stage to track advancement. Thus 
a status (Draft / Open for review / Final / New Release) might also be important.
 DK:=> We need to clarify the modifications that may constitute a new version of an existing 
template, as opposed to a new template. The main guiding principle is that conformant instances 
would remain directly comparable.

==== templateReferenceModelID ==== The globally unique identifier of the reference model against which the Template was developed. The underlying reference model may be A DIM, LIM, or Profile or Template.

LM: Templates can be constraints against numerous models.  These are shown using derivation
 relationships to the models derived from (RIM, DIM, CIMs, other LIMs, etc.
DK: Yes, a given template might apply to more than one model, but will inevitably have been 
designed with one in mind, and it will be optimized for this. An alternative approach would 
be to list the models for which the template has been “certified” for use i.e. some verification 
has been undertaken to ensure that instances can be constructed that are faithful to the template.
 However, given how far we are from achieving such certification, I would suggest we leave this
 requirement as it is.

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

Open Issue: What form should this identifier take? This will be addressed in the Template Implimentation guide, and will likely be ITS dependent.

LM: Have added a URL for the ‘primary’ repository.  Note that a given template can be stored in numerous repositories and it doesn’t make sense to include all in the metadata, especially as it will change over time.  However, I’ve added primary repository as the location most likely to contain updates, new versions, etc.  I’ve also used a URL rather than an id because an id doesn’t buy you much.
WG: Possibly also refer to multiple repositories i.e. to have the language issues tackled. (Dutch Apgar at NICTIZ? English at???). 
DK: I think that even language translations must be consolidated within a single reference copy of the template. The template itself needs to document the reference repository that can be queried to ensure that a particular version that you hold is still current. This does not prevent multiple copies existing, but provides a mechanism to enable currency to be verified. An alternative is a single central index that knows the repository holding the master version and version status of each template, but this is too complex an infrastructure for the near future.

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

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

LM:Because I’ve changed the repository id to a URL, I don’t think we need the name of the 
authority.  You can look it up by going to the URL.  If you’re searching for a template, 
then you’re generally searching within a single repository anyhow, so the assigning organization 
name isn’t going to help much.  No plans to support this in the MIF unless a stronger case is 
made for adding it.
WG:I miss the authorship. The one(s) writing the template and additional information, must 
be identified. This is usually not the one registering the template. I miss the source 
material used. Templates can come from assessment scales, requiring linkage to scientific 
sources, or based on guidelines referring to the particular guideline, or a project document 
etc.
DK:=I am not sure where the properties William mentions have gone: they are in the CEN/openEHR
 archetype requirements. I do agree that we need to add the identifier of the certification body 
who has certified this template, if it has been certified. More work is needed on a certification
 data set, which we are doing in Europe through 2006.

Identification Metadata - Optional


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

LM: Will be added as a template-specific item.  Is the intent to be definitional?  
I.e. This template represents the definition of what is meant by the LOINC term “blood pressure”?
WG: Agree for the moment, but would need to see the implementation if this is OK. Currently 
we deal with codes concepts on the template level, but also on the variable list which can
 be expressed in a template, see Barthel Index which has 10 concepts underlying. 
DK: We need to clarify how this differs from the Template Name. Do we really need both
 a free text and a coded term for the same thing? My intention originally was to offer 
either (since codes will not exist for some template concepts) but not both! Can I suggest
 that we consider combing these two attributes into a single “text or code” representation?

Description Metadata – Mandatory


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

This is description.text.language.  (All annotations including purpose, rationale, usage 
notes, etc. allow multiple translations.)  Language isn’t mandatory.  If not specified, it 
is inferred by the realm in which the template is created.

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

This is the description annotation.  (Note that the definition here overlaps considerably with 
your ‘Intent’ earlier.  From the MIF, the difference between Description and UsageNotes is that
 description talks about what something ‘is’.  UsageNotes talk about what should or should not 
be done with it. Note that this isn’t mandatory, though we could add a Schematron rule makes it
 mandatory for the static model level for LIMs (templates) if you want.
WG: See our format: goal, underpinning, variable list, instructions for clinical use, 
interpretation, literature, examples from paper world, mapping from natural language to 
HL7, model itself. Etc. 
DK: William provides a useful list here. In discussing this description set structure within 
CEN we decided not to break down the description into those headings specificaslly, but to 
offer an informal note to recommend that those themes should be included in the detailed 
description (defined below) if relevant.

Description Metadata – Optional


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

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

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

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


Publication Metadata – Mandatory


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

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

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

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

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

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

Publication Metadata – Optional


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

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


Template Node Constraints

templateNodeExplicit

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

templateNodeId

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

templateNodeReferenceModelID

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


templateNodeReference

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

inclusionRationale

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

templateReferenceId

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

templateNodeReferenceId

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


templateNodeConstrained

Another template node referenced by required attributes?? That is not defined by identifier but by rules governing allowed template nodes.


templateNodeChoice

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


templateNodeConstraint

Constrains allowed nodes based on the attributes of a template node definiton. This inclusion constraint may be made against explicit or referenced template nodes.

inclusionRationale

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

constraintStatement

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

cardinality

Constraints on the number of instances that can be instantiated corresponding to this template node.

logicalCondition

Constraint rule expression statement. This may include references to environmental parameters, relatively referenced instances or absolutely referenced instances.

expressionFormalism

The expression formalism used to express the logical condition. Such as OWL, OCL, GELLO etc.


codedTermBinding

Every template node must be associated with at least one clinical term.

Issue: not all nodes can be bound to clinical concepts

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

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

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


attributeConstraints

A template node may specify constraints on attributes corresponding to a reference model.

This covers the case where RIM class attributes are constrained further as required by a particular template. This includes:

  • Restricting cardinality e.g. 0..* to 1..1
  • Restricting a data type to a specialisation e.g. GTS to TS (this is the equivalent to Data Type flavours)

Issue: this now asserts that datatypes are definately part of the reference model; NOT data values as examined in the next section.


attributeName

Name of the attribute corresponding to the underlying reference model.

attributeCode

Label/code of type of attribute describing its context. This may be role code, type code, etc.

cardinality

Cardinality constraints may be defined on instantiation of attributes.

instantiationConstraint

Other constraints or rules may be specified in a desired expression formalism.

collectionType

Multiple instances can be specified as unordered list, ordered list or a unique instance set.


HL7 Template Data Value Constraints

structuralAttributeConstraints


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

- in process

dataValueConstraints


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

  • Null and null flavor values as well as an optional reason to specify a null flavor value.
  • If the constraint or rule specifies inclusion or exclusion criteria.
  • The formalism (including version) in which this constraint specification is represented.
  • The intended fixed (prescribed) value for conforming instances.
  • The intended default value for conforming instances.
  • A list of permitted candidate values for conforming instances (i.e. to be a subset of those vales legally permissible in the underlying Reference Model.)

Quantity data types must be able to specify


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

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

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

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


Date data types must be able to specify


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

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

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


Textual Data Types


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

codingScheme


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


Logic Operators


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

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

Template Reference


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

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

The occurrence in the instance hierarchy

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

Template Assertions

Static assertions


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

Co-occurrence Assertions


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

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

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

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

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

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


Containment Assertions


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

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