1.                   
Version 2 Standard Quality Criteria

Chapter Co-Chair and Editor: (1)

Anthony Julian
Mayo Clinic

Chapter Co-Chair

Nick Radov

United HealthCare Services, Inc

Chapter Co-Chair

Sandra Stuart
Kaiser Permanente Information Technology

Editor (2)

 

Craig Newman

Altarum

Conformance  Co-Chair

Nathan Bunker

American Immunization Registry Association

 

Conformance Co-Chair

Frank Oemig
Deutsche Telekom Healthcare and Securitey Solutions GmbH, HL7 Germany

Conformance Co-Chair

Ioana Singureanu

Eversolve, LLC

 

Conformance  Co-Chair

Robert Snelick
National Institute of Standards and Technology (NIST)

Sponsoring Work Group:

Infrastructure and Messaging

List Server:

inm@lists.hl7.org

Notes to Balloters

This is the first comment ballot for Version 2 quality criteria.

Please ballot on chapter content only. The formatting of the chapters is consistent with that for the standard, mainly driven by the requirement to automatically extract data for automatic consistency checking and to build the HL7 v2.9 Database. The format has been reviewed by the HL7 Architectural Review Board. As HL7 also intends to publish the Standard in PDF and HTML/XML format, variations in presentation may not be avoidable. For this reason, not all style enhancements have change marks.

 

 

 

 

 

 

1.1            Chapter  contents

1. Version 2 Standard Quality Criteria

1.1 Chapter  contents

1.2 Overview

1.3 Need

1.4 Explanation of Quality Criteria

1.5 Document Metadata

1.6 Context and Use Cases

1.7 Technical Requirements – General

1.8 Technical Requirements – Trigger events

1.9 Technical Requirements – Messages

1.10 Technical Requirements – Segments

1.11 Technical Requirements – Fields

1.12 Technical Requirements – Data types

1.13 Technical Requirements – Examples

2. 1 V2 IG Quality Criteria

2.2 Document Metadata

2.3 Context and Use Cases

2.4 Technical Requirements – General

2.5 Technical Requirements – Messages

2.6 Technical Requirements – Segments

2.7 Technical Requirements – Fields

2.8 Technical Requirements – Data types

2.9 Technical Requirements – Value sets

2.10 Technical Requirements – Examples

1.2            Overview

This document contains a proposed starting set of Health Level Seven (HL7) Version 2 (V2) Standard and Implementation Guide Quality Criteria.   Once finalized, the V2 Management Group will be responsible for evaluating the degree to which all HL7 V2 standards meet these criteria.

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

1.4            Explanation of Quality Criteria

The quality criteria are broken into related sets of criteria applying to particular portions of a HL7 V2 standard.

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 with which all HL7 V2 standards SHALL (or SHALL NOT) conform.
  • Best Practice - These are quality criteria with which all HL7 V2 standards SHOULD (or SHOULD NOT) conform.

These quality criteria SHALL be applied regardless of the ballot level of the content.

1.5            Document Metadata

  1. Criterion – The chapter SHALL have a defined purpose.
  2. Criterion - The chapter SHALL have a list of message types defined in the chapter.
  3. Criterion –The chapter SHALL have a list of trigger events defined in the chapter.
  4. Criterion –The chapter SHALL have a list of message segments defined in the chapter.
  5. Criterion - The chapter SHALL NOT duplicate message segment definitions for segments defined in other chapters.
  6. Criterion – The chapter SHALL be published according to the HL7 V2 Style guide in effect at the time of publishing.
  7. Criterion – Chapter Chairs and Editor(s) SHALL be listed
  8. Criterion - The chapter SHALL list the Sponsoring work group(s).
  9. Best Practice – The chapter SHOULD have examples.
  10. Best Practice - The chapter SHOULD describe implementation considerations including issues that must be addressed in planning an implementation.
  11. Best Practice - The chapter SHOULD describe any outstanding issues.

1.6            Context and Use Cases

  1. Criterion - The purpose and audience of each use case in the chapter SHALL be   described.
  2. Criterion - The scope (both in and out of scope) of each use case in the chapter SHALL be   clearly defined.

1.7            Technical Requirements – General

  1. Criterion –A V2 specification SHALL follow the rules defined in the most current version of the conformance methodology specification <<link here once standalone Conformance document is available>> .
  2. Criterion –A V2 specification SHALL NOT make or imply assumptions about
    1. The ownership of data.
    2. Subsequent actions of recipients
    3. Design or architecture of application systems

1.8            Technical Requirements – Trigger events

Definition :   A trigger event is a real-world event that creates the need for data to flow.   A trigger event code is an identifier

  1. Criterion – Trigger events SHALL be unique across the HL7 V2 standards. e.g. A03, R01
  2. Criterion - A trigger event code SHALL NOT be associated with more than one message type.

1.9            Technical Requirements – Messages

  1. Criterion – Each Message SHALL be defined using the abstract syntax defined in Chapter 2: section "Message representation."
  2. Criterion – Each message SHALL have a message type that defines its purpose. E.G. ADT, ORU  
  3. Criterion – Each message structure   SHALL have a unique identifier which is named by the message type, underscore, trigger event.   E.G. ADT_A03,   ORU_R01.
  4. Criterion - Each message structure SHALL NOT be required to be unique across multiple trigger events within a message type.
  5. Criterion - Each messages structure SHALL be restricted for use withing the defined message type. E.G. Structure ORU_R01 CAN NOT be used in a message of type ADT.
  6. Criterion -   Each message structure definition SHALL   include a narrative description   describing the role of the message.
  7. Criterion -   While there is no mandate for segment groups, when one or more segment groups are defined each segment group SHALL have a unique name within the message structure with uppercase letters, numbers or   underscores following the XML specification for element names which SHALL NOT change over time.
  8. Criterion -The first segment of a segment group defined after Version 2.5 SHALL be required.

1.10       Technical Requirements – Segments

  1. Criterion – Each segment SHALL be defined in accordance with the HL7 V2 Style guide in effect at the time of publishing.
  2. Criterion – Each segment SHALL have a unique ID code which SHALL NOT begin with the letter Z.
  3. Criterion - Each new segment SHALL require an action code and unique identifier (See Control chapter, "Protocol for interpreting repeating segments or segment groups in an update Message" )
  4. Criterion - New segments, or changes in the usage of existing segments, SHALL be harmonized across all possible use of the segment(s), and variances documented and approved by the methodology group - Infrastructure and Messaging .

1.11       Technical Requirements – Fields

  1. Criterion – Field definitions SHALL comply with the HL7 V2 Style guide in effect at the time of publishing.
  2. Criterion – Field definitions SHALL be sufficiently explained for an implementer or analyst who is not a SME to understand the usage.
  3. Best Practice - For Versions 2.3 and higher: the optionality of fields SHOULD be explicitly documented in the segment field definitions that follow each segment definition table;including explicit documentation of optionality based on trigger event.
  4. Criterion – Field definitions for composite fields SHALL NOT have a length
  5. Criterion – Field definitions SHALL use data types defined in the standard.

1.12       Technical Requirements – Data types

  1. Criterion – Data types SHALL be defined in the Data Types section.
  2. Criterion - Data types SHALL not be redefined based on use case.
  3. Criterion Data types SHALL NOT be extended with additional components in field definitions .
    1. If a new data type component is needed, it SHALL be added to the base standard through the HL7 V2 proposal process.
  1. Criterion - Standard text describing   the use and construction of value sets SHALL be included.
  2. Criterion - Vocabulary SHALL be created or extended according to the rules in Chapter 2.c "Code Tables".

1.13       Technical Requirements – Examples

  1. Criterion - Each use case SHALL contain at least one full example message for each trigger event.
     
  2. Best Practice -   "message snippets" SHOULD NOT be used unless the example can be unambiguously located within the message structure and can be interpreted without knowledge of content in other parts of the message (eg. a snippet of the Visit segment group is appropriate when the message structure contains only a single Visit segment group)
  3. Best Practice -   Segments that are not relevant for the point being made MAY be abbreviated in the context of a full message
  4. Criterion - Example messages SHALL be prefaced with standardized text indicating that they should not be used for the purposes of coding and are only for the purposes of better understanding the requirements


2.1                      V2 IG Quality Criteria

2.2                      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

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

2.4                      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

2.5                      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

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

2.7                      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

2.8                      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

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

2.10                 Technical Requirements – Examples

  1. Criterion - Each use case SHALL contain at least one full example message for each profile
  2. Best Practice -   "message snippets" SHOULD NOT be used unless the example can be unambiguously located within the message structure and can be interpreted without knowledge of content in other parts of the message (eg. a snippet of the Visit segment group is appropriate when the message structure contains only a single Visit segment group)
  3. Best Practice -   Segments that are not relevant for the point being made MAY be abbreviated in the context of a full message
  4. Criterion - Example messages SHALL be prefaced with standardized text indicating that they should not be used for the purposes of coding and are only for the purposes of better understanding the requirements