Difference between revisions of "Reading Guide for Publication Artifacts"
(→Table view of Template Design) |
|||
| (13 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | =How to read the table view for templates= | |
| − | The template definitions are shown in a table view. It is comprised of ''Template Meta data'' and the ''Template Design''. For further information please refer to the HL7 Templates Standard: Specification and Use of Reusable Information Constraint Templates, Release 1 | + | The template definitions are shown in a table view. It is comprised of ''Template Meta data'' and the ''Template Design''. For further information please refer to the HL7 Templates Standard: Specification and Use of Reusable Information Constraint Templates, Release 1<ref name="teits"/>. |
Templates may also be included in the hierarchical graph view (often used for CDA), see below. | Templates may also be included in the hierarchical graph view (often used for CDA), see below. | ||
| − | + | ==Template Meta data== | |
| − | {{IncludeImage|TemplatePublication1.png|750px| | + | {{IncludeImage|TemplatePublication1.png|750px|100%}} |
The upper right part of the template table contains the template meta data. Template id, status and the template name are shown (1). Furthermore the Version (effective date), a possible version label and the display name are shown (2). | The upper right part of the template table contains the template meta data. Template id, status and the template name are shown (1). Furthermore the Version (effective date), a possible version label and the display name are shown (2). | ||
| Line 14: | Line 14: | ||
The usage part (5) may list templates that uses this template or what templates this templates uses. A relationship list (6) may show all relationships to other templates or models. | The usage part (5) may list templates that uses this template or what templates this templates uses. A relationship list (6) may show all relationships to other templates or models. | ||
| − | {{IncludeImage|TemplatePublication5a.png|750px| | + | Examples may show the correct use of the template by an XML fragment (7). |
| + | |||
| + | {{IncludeImage|TemplatePublication5a.png|750px|100%}} | ||
| − | + | The relationship list shows all relationships to other templates or models for this template. It is divided in the "Used by" part listing templates that make use of this template, and a "Uses" listing all templates that are used by this templates, either as inclusion or containment. Indirect relationships like the parent Document Level Template for a Section Level Template are marked with a chain symbol. | |
The PDF version is rendered in the same way, but maybe with different fonts etc. to fit customized publication requirements. | The PDF version is rendered in the same way, but maybe with different fonts etc. to fit customized publication requirements. | ||
| − | {{IncludeImage|TemplatePublication2.png|750px| | + | {{IncludeImage|TemplatePublication2.png|750px|100%}} |
| − | + | ==Table view of Template Design== | |
| − | {{IncludeImage|TemplatePublication3.png|750px| | + | {{IncludeImage|TemplatePublication3.png|750px|100%}} |
The headings of the table view of a template design are: | The headings of the table view of a template design are: | ||
| Line 29: | Line 31: | ||
'''Item (1)''' contains the XML document tree view of all elements and attributes specified in the template design. Elements are denoted by a preceding triangle and attributes by a preceding "@". | '''Item (1)''' contains the XML document tree view of all elements and attributes specified in the template design. Elements are denoted by a preceding triangle and attributes by a preceding "@". | ||
| − | '''DT (2)''' | + | '''DT (2)''' data types, contains the data type of the item, for more information on valid data types for element and attributes (see <ref name="teits"/>). |
'''Card / Conf (3)''' cardinality (Card) and conformance (Conf) of the item. | '''Card / Conf (3)''' cardinality (Card) and conformance (Conf) of the item. | ||
| Line 40: | Line 42: | ||
|O || optional || Data is truly optional | |O || optional || Data is truly optional | ||
|- | |- | ||
| − | |R || required || If data is present and not masked (e.g. for privacy reasons), it must be provided, otherwise it may be omitted or explicitly null flavored | + | |R || required || If data is present and not masked (e.g. for privacy reasons), it must be provided, otherwise it may be omitted or explicitly null flavored.<br/>Sender and receiver must support this element. |
|- | |- | ||
| − | |M || mandatory || The data must be populated with a valid value from the associated value domain, otherwise the instance is not valid and may not be communicated | + | |M || mandatory || The data must be populated with a valid value from the associated value domain, otherwise the instance is not valid and may not be communicated.<br/>Sender and receiver must support this element. |
|- | |- | ||
| − | |C || conditional || There are conditions when data has to be provided (e.g. co-constraints like "information about pregnancy IF the patient is "female" | + | |C || conditional || There are conditions when data has to be provided (e.g. co-constraints like "information about pregnancy IF the patient is "female".<br/>Sender and receiver must support this element. |
|- | |- | ||
| − | |F || fixed || The data has a fixed value | + | |F || fixed || The data has a fixed value. |
|- | |- | ||
| − | |NP || not | + | |NP || not permitted || Data shall not be present |
|} | |} | ||
| Line 56: | Line 58: | ||
===Details of the table view=== | ===Details of the table view=== | ||
| − | {{IncludeImage|TemplatePublication4.png|750px| | + | {{IncludeImage|TemplatePublication4.png|750px|100%}} |
The actual template design shows the XML structure in a hierarchical list of elements (items) that are typically prefixed by the namespace "hl7:" or "cda:" (1). | The actual template design shows the XML structure in a hierarchical list of elements (items) that are typically prefixed by the namespace "hl7:" or "cda:" (1). | ||
| Line 62: | Line 64: | ||
Elements are denoted with a triangle, attributes with an @ sign (2). | Elements are denoted with a triangle, attributes with an @ sign (2). | ||
| − | Data types are specified according to the list of supported data types (3). They may be simple data types (lowercase), regular | + | Data types are specified according to the list of supported data types (3). They may be simple data types (lowercase), regular data types (uppercase) or flavors thereof. |
| + | In case of coded elements, the coding strength (Required/CNE, Extensible/CWE, Preferred or Example) can be highlighted near the datatype (e.g. “CD.IPS (Extensible/CWE)”) ; the absence of indications about the strength (e.g. “CE.IPS”) shall be interpreted as “Required/CNE”. | ||
| + | |||
| + | {| class="wikitable" | ||
| + | |+Values of the coding strength column | ||
| + | ! '''Strength''' !! Displayed as !! 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. | ||
| + | |} | ||
The cardinality and conformance column is explained above (4). | The cardinality and conformance column is explained above (4). | ||
| Line 75: | Line 91: | ||
Inclusion or containments of other templates, e.g. an entry within a section, are shown accordingly (8) along with their template id, display name and flexibility/stability indication, i.e. "DYNAMIC" (the most recent version) or a STATIC binding together with a version date. | Inclusion or containments of other templates, e.g. an entry within a section, are shown accordingly (8) along with their template id, display name and flexibility/stability indication, i.e. "DYNAMIC" (the most recent version) or a STATIC binding together with a version date. | ||
| − | {{IncludeImage|TemplatePublication5b.png|750px| | + | {{IncludeImage|TemplatePublication5b.png|750px|100%}} |
Choices of elements are shown as a choice list with the elements in questions summarised in a bullet point list. | Choices of elements are shown as a choice list with the elements in questions summarised in a bullet point list. | ||
| − | {{IncludeImage|TemplatePublication6b.png|750px| | + | {{IncludeImage|TemplatePublication6b.png|750px|100%}} |
A typical Conformance Statement is the binding of a coded element to a value set. This is expressed in the way shown. The value set is represented with the id, display name and the flexibility/stability of the binding. | A typical Conformance Statement is the binding of a coded element to a value set. This is expressed in the way shown. The value set is represented with the id, display name and the flexibility/stability of the binding. | ||
| − | {{IncludeImage|TemplatePublication6c.png|750px| | + | {{IncludeImage|TemplatePublication6c.png|750px|100%}} |
In case a constraint is expressed in words, a box "Constraint" accompanies the textual expression of the constraint. | In case a constraint is expressed in words, a box "Constraint" accompanies the textual expression of the constraint. | ||
| − | {{IncludeImage|TemplatePublication6a.png|750px| | + | {{IncludeImage|TemplatePublication6a.png|750px|100%}} |
In cases where constraints are expressed by formalised rules in ISO Schematron, the rule along with the role (error, warning), the test and the assertion message is shown. | In cases where constraints are expressed by formalised rules in ISO Schematron, the rule along with the role (error, warning), the test and the assertion message is shown. | ||
| Line 100: | Line 116: | ||
In case a template has more that one type (CDA Person for header, section and entry templates), it is denoted with a *, if a recursive definition is detected, this is shown with the symbol @. | In case a template has more that one type (CDA Person for header, section and entry templates), it is denoted with a *, if a recursive definition is detected, this is shown with the symbol @. | ||
| + | |||
| + | ==How to read the ''where'' criteria == | ||
| + | |||
| + | Templates sometimes include criteria for identifying distinct elements from a list (e.g. in a choice). | ||
| + | |||
| + | The criteria used to identify the items are shown in square brackets using the assertion ''where [ criteria ]'' | ||
| + | |||
| + | Criteria can be: | ||
| + | # an '''xpath expression''' as in the example : ''where [hl7:low or hl7:high]'' | ||
| + | # or an '''integer''' indexing the items of the list: e.g. ''where [1]; where [2]'' | ||
Latest revision as of 19:44, 8 September 2019
Contents
How to read the table view for templates
The template definitions are shown in a table view. It is comprised of Template Meta data and the Template Design. For further information please refer to the HL7 Templates Standard: Specification and Use of Reusable Information Constraint Templates, Release 1[1].
Templates may also be included in the hierarchical graph view (often used for CDA), see below.
Template Meta data
The upper right part of the template table contains the template meta data. Template id, status and the template name are shown (1). Furthermore the Version (effective date), a possible version label and the display name are shown (2).
The description area (plain or an accordion) contains the template descriptions/purpose (3), followed by classifications and whether the template is defined as open or closed (4).
The usage part (5) may list templates that uses this template or what templates this templates uses. A relationship list (6) may show all relationships to other templates or models.
Examples may show the correct use of the template by an XML fragment (7).
The relationship list shows all relationships to other templates or models for this template. It is divided in the "Used by" part listing templates that make use of this template, and a "Uses" listing all templates that are used by this templates, either as inclusion or containment. Indirect relationships like the parent Document Level Template for a Section Level Template are marked with a chain symbol.
The PDF version is rendered in the same way, but maybe with different fonts etc. to fit customized publication requirements.
Table view of Template Design
The headings of the table view of a template design are:
Item (1) contains the XML document tree view of all elements and attributes specified in the template design. Elements are denoted by a preceding triangle and attributes by a preceding "@".
DT (2) data types, contains the data type of the item, for more information on valid data types for element and attributes (see [1]).
Card / Conf (3) cardinality (Card) and conformance (Conf) of the item. Cardinality is the usual notion of min and max occurrences of the element. For attributes 0..1 denotes optionality, 1..1 say that the attribute is required and NP denotes prohibited attributes. Conformance may display values as shown in the following table.
| Conf | Short | Description |
|---|---|---|
| O | optional | Data is truly optional |
| R | required | If data is present and not masked (e.g. for privacy reasons), it must be provided, otherwise it may be omitted or explicitly null flavored. Sender and receiver must support this element. |
| M | mandatory | The data must be populated with a valid value from the associated value domain, otherwise the instance is not valid and may not be communicated. Sender and receiver must support this element. |
| C | conditional | There are conditions when data has to be provided (e.g. co-constraints like "information about pregnancy IF the patient is "female". Sender and receiver must support this element. |
| F | fixed | The data has a fixed value. |
| NP | not permitted | Data shall not be present |
Description (4) contains a textual description of the item, may also contain constraints and values for fixed attributes.
Label (5) is a human readable label that is displayed upon errors, warnings or notes during validation.
Details of the table view
The actual template design shows the XML structure in a hierarchical list of elements (items) that are typically prefixed by the namespace "hl7:" or "cda:" (1).
Elements are denoted with a triangle, attributes with an @ sign (2).
Data types are specified according to the list of supported data types (3). They may be simple data types (lowercase), regular data types (uppercase) or flavors thereof. In case of coded elements, the coding strength (Required/CNE, Extensible/CWE, Preferred or Example) can be highlighted near the datatype (e.g. “CD.IPS (Extensible/CWE)”) ; the absence of indications about the strength (e.g. “CE.IPS”) shall be interpreted as “Required/CNE”.
| Strength | Displayed as | 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. |
The cardinality and conformance column is explained above (4).
Fixed values for e.g. attributes are also shown in the "description" column (5), preceded by a "F" in the Conf column.
Conformance statements are shown together with a CONF box, e.g. a @code and a @codeSystem with fixed and required values (6).
An optional label is displayed at the rightmost column (7).
Inclusion or containments of other templates, e.g. an entry within a section, are shown accordingly (8) along with their template id, display name and flexibility/stability indication, i.e. "DYNAMIC" (the most recent version) or a STATIC binding together with a version date.
Choices of elements are shown as a choice list with the elements in questions summarised in a bullet point list.
A typical Conformance Statement is the binding of a coded element to a value set. This is expressed in the way shown. The value set is represented with the id, display name and the flexibility/stability of the binding.
In case a constraint is expressed in words, a box "Constraint" accompanies the textual expression of the constraint.
In cases where constraints are expressed by formalised rules in ISO Schematron, the rule along with the role (error, warning), the test and the assertion message is shown.
How to read the Templates hierarchical graph view
Templates are often included in the hierarchical graph view (often used for CDA). It gives an overview of e.g. section and entries and their nesting/relationships.
In case a template has more that one type (CDA Person for header, section and entry templates), it is denoted with a *, if a recursive definition is detected, this is shown with the symbol @.
How to read the where criteria
Templates sometimes include criteria for identifying distinct elements from a list (e.g. in a choice).
The criteria used to identify the items are shown in square brackets using the assertion where [ criteria ]
Criteria can be:
