Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

Table of Contents

The below listed quality criteria SHALL be applied to HL7 Version 2 balloted Implementation Guides (IG) and are best practices for locally derived 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


  • 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
    • An IG SHALL include fully defined choreography describing the message flows and profiles to fulfill the use cases.
      • This SHALL be expressed either graphically or textually.

Technical requirements


  • An IG SHALL follow the rules defined in the conformance methodology specification. <<link here >>
  • An IG SHOULD be based on the most relevant version of the standard, and avoid "pre-adoption".
  • Conformance statements SHALL be testable or SHALL be sufficiently defined that a computable statement can be derived from it.
  • 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.


  • Each message SHALL be associated with a Profile ID to be placed in MSH-21.
  • Each profile SHALL require MSH-21 to be valued with at least one profile identifier as defined in the conformance methodology specification<<link here>>.
  • Each message definition SHOULD include a narrative description regarding the role of the message in one or more use cases


  • Segments and Segment Groups in the message SHALL have a Usage and a Cardinality
  • Segments not defined in the base standard for the trigger event being used SHALL NOT be included in the IG.
  • Segments defined in the IG SHALL 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 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 Usage of R, RE or C Which have a coded data type (CWE, CNE, ID, IS, etc) SHOULD be bound to a value set or code system described elsewhere in the document as defined in the conformance specification<<link here>>
  • Fields not defined in the base standard SHALL NOT be included in the IG.  If a new field is needed, it SHOULD be added through HL7 V2 processes.

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


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

Discussed at 2019-ATLANTA WGM

  • No labels