Skip to end of metadata
Go to start of metadata

Table of Contents

The following criteria will be applied to HL7 Version 2 Implementation Guides (IG):

Document meta-data

  • Title SHALL match the official HL7 name for publication including:
    • Base version SHALL be specified
      • Any pre-adoption or post-adoption SHALL be clearly outlined
    • Realm SHALL be specified
    • Document type SHALL be (STU, Normative, Informative)
  • Publication date SHALL be  specified
  • Title page SHALL BE  the official HL7 title page including official copyright text
  • Where appropriate, terminology text is included
  • Table of contents SHALL exist and include lists of tables and figures (note that message, segment, data type and value set "tables" MAY not be explicitly listed)
  • Authors and contributors SHALL be  listed
  • Sponsoring work group(s) SHALL be listed

Context

  • Purpose and audience of the document SHALL be  described
  • Scope (both in and out of scope) of the document SHALL be  clearly defined

Use Cases

  • At least one use case SHALL be described
    • The requirements of the use case SHALL be represented as constraints in the profiles
    • The profiles SHALL NOT contain constraints that are not required for the IG use case(s) 
  • Use cases SHALL include
    • Actors
    • User story
    • Message flows including a list of message profiles used to fulfill the use case

Technical requirements

General

  • An IG SHOULD be based on the most relevant version of the standard, and avoid "pre-adoption".
  • Conformance statements SHALL be testable
  • Declared conditional elements SHALL have a predicate that is machine computable given the contents of the message
  • Each conformance statement SHALL have a unique ID
    • Conformance statement IDs need not be meaningful or in alphabetical/numeric order
    • Conformance statement IDs SHOULD  be consistent between releases of the same IG
    • Conformance statement IDs SHALL NOT  be reused for different requirements within the document or between releases of the same IG
      • Conformance statements MAY be reused within a document if the requirement is applied to multiple locations in the message
        • 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 can be reused in both locations
  • An IG SHALL NOT use z-segments or custom data types (note that a constraint of a base data type is not a "custom data type")
  • An STU IG SHALL have the same technical requirements as a Normative IG.

Messages

  • Each message SHALL be associated with a Profile ID for use in MSH-21
  • Each message SHOULD include a narrative description regarding the role of the message in one or more use cases

Segments

  • Segments and Segment Groups in the message SHALL have a Usage and a Cardinality
  • Segments not defined in the base standard SHALL NOT be included in the IG.
  • Segments with a Usage of R, RE or C SHOULD  point to a constrained description of the segment elsewhere in the document
    • The exception to this is where a segment is required within an optional segment group (eg 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 document (it just defaults to the based standard definition)

Fields

  • Fields in the message SHALL have a Usage and Cardinality which SHALL NOT be in conflict with the base standard.
  • Fields with a Usage of R, RE or C SHALL point to a constrained description of the field elsewhere in the document
  • Fields with a coded data type (CWE, CNE, ID, IS, etc) SHOULD be bound to a value set described elsewhere in the document
  • Fields not defined in the base standard SHALL NOT be included in the IG.

Data type

  • Where possible, standardized data type flavors should be use (see data type flavor project).
  • Data types SHALL NOT be extended with additional components.

Value sets

  • Standard text describing the use and construction of value sets SHALL be included
    • We'd need to develop this (possibly starting with NIST text or text in the immunization IG)
  • Each value set should have an OID
  • Each value set should be declared as open or closed and static or dynamic
    • We'll need to provide a reference to definitions for these attributes
  • Each value in a value set should include Usage
  • Values should only be required when they are critical to the fulfilment of one or more use cases
  • Only value sets which are bound to a field, data type or co-constraint SHALL be included in the IG
  • Should value sets have gone through the harmonization process?
    • Need to talk to Vocab about this

Examples

  • Each use case SHALL contain at least one full example message for each profile
  •  "message snippets" SHALL NOT be used
    • segments that are non-relevant for the point being made may be abbreviated in the context of a full message
  • 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



Discussed on 2019-03-14 telcon.


  • No labels

18 Comments

  1. Should we add a document metadata bullet point to specify the sponsoring work groups, if applicable?

  2. Under Technical Requirements Segments I recommend adding "Additional fields not defined in the baseline Segment definition SHALL NOT be appended".

  3. Should we add a document metadata bullet point with a "SHOULD" recommendation to include the URL of the HL7.org web page containing the IG? People often pass around IGs as email attachments and then they end up with outdated copies. So I'd like everyone to know where to go to find more information and download the latest version.

    1. Good Idea.  Would be problematic unless we have HL7 create a permalink for each IG.

  4. We should state whether or not there are any differences between STU and Normative IGs. I suspect there won't be, but we should say so one way or the other.

  5. There needs to be language enjoining IG creators to make the document accessible to reviewers.   This includes not putting redundant content in.   I have seen that as an issue for documents created from IGAMT in which use of profile components ends up creating multiple dummy segment flavors which appear in the IG.

  6. We should also think about best practices for:

    • pre-adoption versus post-adoption
    • slicing by occurrence (ex. first occurrence must be the legal name and the second occurrence must be the "nickname" an dif there is no legal name, then the first occurrence must be empty) 
    1. RE: Slicing by occurrence:

      IMHO This should be considered on a case-by-case basis, and not a general rule:

      PID-13 stated "The first sequence is considered the primary number (for backward compatibility).  If the primary number is not sent, then a repeat delimiter is sent in the first sequence" -

      but PID-40 (the replacement as of 2.7) states "This field replaces PID-13 – Phone Number - Home and PID-14 – Phone Number – Business with the intention that the components of the XTN data type be used to identify phone usage (Telecommunication use code) and type of equipment (telecommunication equipment type). Jointly, these components will describe the nature of the telecommunication data contained in this field and removes the sequenced-based assumptions in PID-13 and PID-14."

      I do not see a valid reason to reverse this statement in an IG.

      Ditto for PID-5 Patient name.  The standard clearly states "The XPN.7 Name Type Code, and not the order, conveys how the name should be interpreted. As of v2.7, Name Type Code is Required. Refer to HL7 Table 0200 - Name Type in Chapter 2C, Code Tables, for valid values.  Specification of meaning based on sequence is deprecated."

      I do not see a valid reason to reverse this statement in an IG either. 

      I will agree that the IG may restrict the name types requiring some, but I am not in favor of restricting the order.


    2. RE: pre-adoption versus post-adoption

      Pre-adoption means that you want to pick and choose which new features of the standard you want to adopt. 

      The purpose of a standard is to standardize. 

      IMHO - although there has been a precedent set, this is bad practice and should be disallowed.

  7. Proposed wording for a "slicing" best practice:

    For fields that can repeat, a given occurrence number SHOULD NOT be designated for a particular type of data (eg, the first occurrence shall be the legal name). Rather, where the data type used contains a "type" component (eg. name type, address type, use code, etc), the type component SHOULD be required and used to indicate the particular type of data being conveyed.

  8. while pre- or post-adoption may be allowed, do we want to say that the "base" version is applied at the IG level rather than at the profile level? In other words, within a single IG, can one profile be based on v2.3.1 while another profile is based on v2.5.1 or should all profiles be based on the same base standard version?

    1. IMHO Version should be specified at the IG level; profiles within the IG can then further restrict.  Allowing profiles to specify alternate versions leads to chaos.

  9. We need to think about the selective adoption guidance before we finalize guidance on version selection.

  10. We should add guidance on release numbering. What is the process for determining the appropriate numbering. Lynn may already know about existing documentation we can point to.

    1. Definitely need to get input from Lynn Laakso on release numbering.  I <<think>> there are some sticky ANSI rules.

  11. We should comment on a minimum allowed base version (eg 2.5.1) if we want projects to have a floor.

    1. IMO projects intended to align with U.S. MU requirements should base on 2.5.1.  Those with no such limitations should only be allowed against current, or current -1.