Health Level Seven (HL7) See Version 2 (V2) Implementation Guide (IG) Quality Criteria

...

Co-Chair

...

Anthony Julian
Mayo Clinic

...

Editor

...

Craig Newman

Altarum

...

Co-Chair

...

Nick Radov

United HealthCare Services, Inc

...

Co-Chair

...

Sandra Stuart
Kaiser Permanente Information Technology

...

Sponsoring Work Group:

...

Infrastructure and Messaging

...

List Server:

...

inm@lists.hl7.org

Overview

This document contains a proposed starting set of v2 Implementation Guide (IG) Quality Criteria. The initial set of criteria are based on the v2 IG quality criteria developed by the Infrastructure and Messaging (InM) work group. This draft for comment ballot is intended to gather comments on this starter set of criteria. Once finalized, the v2 Management Group will be responsible for evaluating the degree to which all HL7 v2 IGs meet these criteria.

Need

In 2017, the HL7 Standards Governance Board (SGB) established the following precept for HL7 Product Quality:

For each family, methodology determines what the quality criteria are, and the management groups establish a plan to ensure the criteria are applied.

As part of the establishment of the v2 Product Family the InM Work Group was identified as the v2 methodology group and assigned the task of developing the set of quality criteria for v2 related products to be implemented by the v2 Management Group.

Note to Balloters

When commenting on the Criteria, please be as specific as possible. For instance:

• Provide suggested wording if you want to see a proposed criteria revised
• Provide the text for any proposed new criteria you believe are missing
• Please provide a clear rationale for why you are requesting a particular change

Explanation of Quality Criteria

The quality criteria are broken into related sets of criteria applying particular portions of a v2 Implementation Guide. This includes criteria concerning the title page and front matter, messages/segment groups/segments, value sets and terminology and examples. There are two types of quality criteria identified:

• Criterion - These are quality criteria that all v2 Implementation Guides SHALL (or SHALL NOT) conform with.
• Best Practice - These are quality criteria that all v2 Implementation Guides SHOULD (or SHOULD NOT) conform with.

Note that the same quality requirements are to be applied to both Normative and STU Implementation Guides.

V2 IG Quality Criteria

Document Metadata

1. Criterion – The title SHALL match the official HL7 name for publication including:
1. The base version SHALL be specified
2. The realm SHALL be specified
3. The document type SHALL be specified (STU, Normative, Informative)
2. Criterion – The publication date SHALL be  specified
3. Criterion – The title page SHALL be  the official HL7 title page including applicable logo and official copyright text
4. Criterion - Where appropriate, terminology text SHALL  be included
5. Criterion – A table of contents SHALL exist and include lists of tables and figures (note that message, segment, data type and value set "tables" MAY be explicitly listed but are not required)
6. Criterion - Authors and contributors SHALL be  listed
7. Criterion - Sponsoring work group(s) SHALL be listed

Context and Use Cases

1. Criterion - The purpose and audience of the document SHALL be  described
2. Criterion - The scope (both in and out of scope) of the document SHALL be  clearly defined
3. Criterion - At least one use case SHALL be described
1. The requirements of the use case SHALL be represented as constraints in the profiles included in the IG
2. The profiles SHALL NOT introduce constraints or requirements that are not required for the IG use case(s) 
4. Criterion – The use case(s) SHALL include
1. Actors
2. User story
3. The fully defined choreography describing the message flows and profiles to fulfill the use case(s).

1. This choreography SHALL be expressed either graphically or textually.

Technical Requirements – General

1. Criterion - An IG SHALL follow the rules defined in the most current version of the conformance methodology specification <<link here once standalone Conformance document is available>>
2. Best Practice - An IG SHOULD be based on the most relevant version of the standard, and avoid "pre-adoption" of content from later versions of the base standard

1. Any pre-adoption or post-adoption SHALL be clearly outlined

1. Criterion - Conformance statements SHALL be testable and SHALL be sufficiently defined so that a computable statement can be derived from it. A computable statement MAY be provided in the IG.
2. Criterion - Declared conditional elements SHALL have a predicate that is testable and is sufficiently defined so that a computable statement can be derived and SHALL also have defined “true” and “false” Usage values
3. Criterion - Each conformance statement SHALL have a unique ID
1. Conformance statement IDs need not be meaningful or in alphabetical/numeric order
4. Best Practice - Conformance statement IDs SHOULD  be consistent between releases of the same IG
5. Criterion - Conformance statement IDs SHALL NOT  be reused for different requirements within the IG or between releases of the same IG
6. Best Practice - Conformance statements SHOULD be reused within a document if the requirement is applied to multiple locations in the message
1. For example, if a conformance statement applies to a field in the OBX segment following both a PID and an OBR segment, then the conformance statement should be referenced in all appropriate locations

Technical Requirements – Messages

1. Criterion - Each message definition SHALL be associated with a Message Profile Identifier
2. Criterion - Each message definition SHALL require MSH-21 to be valued with at least one Message Profile Identifier as defined in the most current version of the conformance methodology specification<<link here>>
3. Best Practice - Each message definition SHOULD include a narrative description regarding the role of the message in one or more use cases described by the IG

Technical Requirements – Segments

1. Criterion - Segments and Segment Groups in the message SHALL have conformance constructs (e.g. Cardinality, Usage, etc) that SHALL be in compliant with the base standard
2. Criterion - Segments not defined in the base standard SHALL NOT be included in the IG (i.e. Z-segments SHALL NOT be part of the IG)
1. If a new segment is needed, it should be added to the base standard through the HL7 V2 process
3. Criterion - Segments with a Usage of R, RE or C(a/b) in the IG SHALL point to a constrained definition of the segment elsewhere in the IG
1. The exception to this is where a segment is required within an optional segment group (e.g. the PATIENT_VISIT segment group is optional, but if included, the PV1 segment is required - in this case, the required PV1 segment does not need to be described in the IG (it defaults to the base standard definition))

Technical Requirements – Fields

1. Criterion - Fields in the message SHALL have conformance constructs (e.g. Data Type, Usage, etc) that SHALL be in compliant with the base standard
2. Criterion - Fields with a Usage of R, RE or C(a/b)  SHALL point to a constrained definition of the field elsewhere in the document
3. Best Practice - Fields with a Usage of R, RE or C(a/b) which have a coded data type (CWE, CNE, ID, IS, etc) SHOULD be bound to a value set, code system or concept domain described elsewhere in the IG as defined in the most current version of the conformance methodology specification <<link here once standalone Conformance document is available>>
4. Criterion - Fields not yet defined in the base standard SHALL NOT be included in the IG
1. If a new field is needed, it should be added to the base standard through the HL7 V2 process

Technical Requirements – Data types

1. Best Practice - Where possible, standardized data type flavors SHOULD be used
1. The data type flavor project provides additional details on the use of standard data types <<link here once data type flavors document is available>>
2. Criterion - Data types SHALL NOT be extended with additional components beyond those described in the base standard
1. If a new data type component is needed, it should be added to the base standard through the HL7 V2 process

Technical Requirements – Value sets

1. Criterion - Standard text describing the use and construction of value sets SHALL be included
2. Best Practice - Each value set SHOULD be referenced by a value set OID
3. Criterion – Each value in the value set SHALL be drawn from a specified code system
4. Best Practice - Each value set SHOULD be declared as static or dynamic
5. Best Practice - Each value set SHOULD be declared as open or closed
6. Best Practice - Each value in a value set SHOULD include a Usage
1. Criterion – Values SHALL only be required when they are critical to the fulfilment of one or more use cases
7. Criterion - Only value sets which are bound to a field, data type or co-constraint SHALL be included in the IG
8. Criterion - Value sets must utilize the Unified Terminology Governance ("UTG") approval process, once the process is in place.
9. Criterion - Value sets must adhere to HL7 Terminology Authority policy, once the policy is in place.

Technical Requirements – Examples

...

Quality Metrics Document